Passwordfile library: Io::PasswordFile Class Reference

Passwordfile library 5.2.1 C++ library to read/write passwords from/to encrypted files

Loading...
Searching...
No Matches
Public Member Functions | List of all members
Io::PasswordFile Class Reference

The PasswordFile class holds account information in the form of Entry and Field instances and provides methods to read and write these information to encrypted files using OpenSSL. More...

`#include <passwordfile.h>`

## Public Member Functions
| PasswordFile ()
| Constructs a new password file.
| PasswordFile (const std::string &path, const std::string &password)
| Constructs a new password file with the specified path and password.
| PasswordFile (const PasswordFile &other)
| Constructs a copy of another password file.
| PasswordFile (PasswordFile &&other)
| Moves the password file.
| ~PasswordFile ()
| Closes the file if still opened and destroys the instance.
CppUtilities::NativeFileStream & | fileStream ()
| Returns the underlying file stream.
void | open (PasswordFileOpenFlags options=PasswordFileOpenFlags::Default)
| Opens the file.
void | opened ()
| Handles the file being opened.
void | generateRootEntry ()
| Generates a new root entry for the file.
void | create ()
| Creates the file.
void | close ()
| Closes the file if currently opened.
void | load ()
| Reads the contents of the file.
std::uint32_t | mininumVersion (PasswordFileSaveFlags options) const
| Returns the minimum file version required to write the current instance with the specified options.
void | save (PasswordFileSaveFlags options=PasswordFileSaveFlags::Default)
| Writes the current root entry to the file under path() replacing its previous contents.
void | write (PasswordFileSaveFlags options=PasswordFileSaveFlags::Default)
| Writes the current root entry to the file which is assumed to be opened and writeable.
void | clearEntries ()
| Removes the root element if one is present.
void | clear ()
| Closes the file if opened.
void | exportToTextfile (const std::string &targetPath) const
| Writes the current root entry to a plain text file.
void | doBackup ()
| Creates a backup of the file.
bool | hasRootEntry () const
| Returns an indication whether a root entry is present.
const NodeEntry * | rootEntry () const
| Returns the root entry if present or nullptr otherwise.
NodeEntry * | rootEntry ()
| Returns the root entry if present or nullptr otherwise.
const std::string & | path () const
| Returns the current file path.
const std::string & | password () const
| Returns the current password.
void | setPath (const std::string &value)
| Sets the current file path.
void | clearPath ()
| Clears the current path.
void | setPassword (const std::string &password)
| Sets the current password.
void | setPassword (const char *password, const std::size_t passwordSize)
void | clearPassword ()
| Clears the current password.
bool | isEncryptionUsed ()
| Returns an indication whether encryption is used and the file is open; returns always false otherwise.
bool | isOpen () const
| Returns an indication whether the file is open.
std::string & | extendedHeader ()
| Returns the extended header.
const std::string & | extendedHeader () const
| Returns the extended header.
std::string & | encryptedExtendedHeader ()
| Returns the encrypted extended header.
const std::string & | encryptedExtendedHeader () const
| Returns the encrypted extended header.
std::size_t | size ()
| Returns the size of the file if the file is open; otherwise returns zero.
std::uint32_t | version () const
| Returns the file version used the last time when saving the file (the version of the file as it is on the disk).
PasswordFileOpenFlags | openOptions () const
| Returns the options used to open the file.
PasswordFileSaveFlags | saveOptions () const
| Returns the save options used the last time when saving the file.
std::string | summary (PasswordFileSaveFlags saveOptions) const
| Returns a summary about the file (version, used features, statistics).

## Detailed Description

The PasswordFile class holds account information in the form of Entry and Field instances and provides methods to read and write these information to encrypted files using OpenSSL.

Definition at line 41 of file passwordfile.h.

## Constructor & Destructor Documentation

## ◆ PasswordFile() [1/4]

Io::PasswordFile::PasswordFile | ( |  | ) |
| explicit

Constructs a new password file.

Definition at line 56 of file passwordfile.cpp.

## ◆ PasswordFile() [2/4]

Io::PasswordFile::PasswordFile | ( | const std::string & | path,
|  | const std::string & | password )
| explicit

Constructs a new password file with the specified path and password.

Definition at line 70 of file passwordfile.cpp.

## ◆ PasswordFile() [3/4]

Io::PasswordFile::PasswordFile | ( | const PasswordFile & | other | ) |

Constructs a copy of another password file.

Definition at line 85 of file passwordfile.cpp.

## ◆ PasswordFile() [4/4]

Io::PasswordFile::PasswordFile | ( | PasswordFile && | other | ) |

Moves the password file.

Definition at line 103 of file passwordfile.cpp.

## ◆ ~PasswordFile()

Io::PasswordFile::~PasswordFile | ( |  | ) |

Closes the file if still opened and destroys the instance.

Definition at line 121 of file passwordfile.cpp.

## Member Function Documentation

## ◆ clear()

void Io::PasswordFile::clear | ( |  | ) |

Closes the file if opened.

Removes path, password and entries and additional information.

Definition at line 675 of file passwordfile.cpp.

## ◆ clearEntries()

void Io::PasswordFile::clearEntries | ( |  | ) |

Removes the root element if one is present.

Definition at line 667 of file passwordfile.cpp.

## ◆ clearPassword()

void Io::PasswordFile::clearPassword | ( |  | ) |
| inline

Clears the current password.

Definition at line 150 of file passwordfile.h.

## ◆ clearPath()

void Io::PasswordFile::clearPath | ( |  | ) |
| inline

Clears the current path.

Causes the file to be closed if currently opened.

Definition at line 117 of file passwordfile.h.

## ◆ close()

void Io::PasswordFile::close | ( |  | ) |

Closes the file if currently opened.

Definition at line 786 of file passwordfile.cpp.

## ◆ create()

void Io::PasswordFile::create | ( |  | ) |

Creates the file.

Does not generate a new root element (see generateRootElement()).

Exceptions

  Throws | ios_base::failure when an IO error occurs.

Definition at line 173 of file passwordfile.cpp.

## ◆ doBackup()

void Io::PasswordFile::doBackup | ( |  | ) |

Creates a backup of the file.

Replaces an existent backup file.

Exceptions

  Throws | ios_base::failure when an IO error occurs.

Definition at line 733 of file passwordfile.cpp.

## ◆ encryptedExtendedHeader() [1/2]

std::string & Io::PasswordFile::encryptedExtendedHeader | ( |  | ) |
| inline

Returns the encrypted extended header.

Definition at line 185 of file passwordfile.h.

## ◆ encryptedExtendedHeader() [2/2]

const std::string & Io::PasswordFile::encryptedExtendedHeader | ( |  | ) | const
| inline

Returns the encrypted extended header.

Definition at line 193 of file passwordfile.h.

## ◆ exportToTextfile()

void Io::PasswordFile::exportToTextfile | ( | const std::string & | targetPath | ) | const

Writes the current root entry to a plain text file.

No encryption is used.

Parameters

  targetPath | Specifies the path of the text file.

Exceptions

  Throws | std::ios_base::failure when an IO error occurs and std::runtime_error when no root entry is present.

Definition at line 691 of file passwordfile.cpp.

## ◆ extendedHeader() [1/2]

std::string & Io::PasswordFile::extendedHeader | ( |  | ) |
| inline

Returns the extended header.

Remarks
  - Returns only unsupported extended data that will be preserved as-is when saving the file.
  - Does not return recognized extended data such as the authentication tag.

Definition at line 169 of file passwordfile.h.

## ◆ extendedHeader() [2/2]

const std::string & Io::PasswordFile::extendedHeader | ( |  | ) | const
| inline

Returns the extended header.

Definition at line 177 of file passwordfile.h.

## ◆ fileStream()

CppUtilities::NativeFileStream & Io::PasswordFile::fileStream | ( |  | ) |
| inline

Returns the underlying file stream.

Definition at line 101 of file passwordfile.h.

## ◆ generateRootEntry()

void Io::PasswordFile::generateRootEntry | ( |  | ) |

Generates a new root entry for the file.

Definition at line 162 of file passwordfile.cpp.

## ◆ hasRootEntry()

bool Io::PasswordFile::hasRootEntry | ( |  | ) | const

Returns an indication whether a root entry is present.

See also
  generateRootEntry()
  rootEntry()

Definition at line 762 of file passwordfile.cpp.

## ◆ isEncryptionUsed()

bool Io::PasswordFile::isEncryptionUsed | ( |  | ) |

Returns an indication whether encryption is used and the file is open; returns always false otherwise.

Remarks
  This method is meant to determine whether encryption is used before loading the file. If the file has already been loaded, use preferably saveOptions().

Definition at line 813 of file passwordfile.cpp.

## ◆ isOpen()

bool Io::PasswordFile::isOpen | ( |  | ) | const
| inline

Returns an indication whether the file is open.

Definition at line 158 of file passwordfile.h.

## ◆ load()

void Io::PasswordFile::load | ( |  | ) |

Reads the contents of the file.

Opens the file if not already opened. Replaces the current root entry with the new one constructed from the file contents.

Exceptions

  Throws | ios_base::failure when an IO error occurs.
  Throws | Io::ParsingException when a parsing error occurs.
  Throws | Io::CryptoException when a decryption error occurs.
  Throws | CppUtilities::ConversionException when a conversion error occurs.

Definition at line 191 of file passwordfile.cpp.

## ◆ mininumVersion()

std::uint32_t Io::PasswordFile::mininumVersion | ( | PasswordFileSaveFlags | options | ) | const

Returns the minimum file version required to write the current instance with the specified options.

Remarks
  This version will be used by save() and write() when passing the same options.

Definition at line 435 of file passwordfile.cpp.

## ◆ open()

void Io::PasswordFile::open | ( | PasswordFileOpenFlags | options = PasswordFileOpenFlags::Default | ) |

Opens the file.

Does not load the contents (see load()).

Exceptions

  Throws | ios_base::failure when an IO error occurs.

Definition at line 129 of file passwordfile.cpp.

## ◆ opened()

void Io::PasswordFile::opened | ( |  | ) |

Handles the file being opened.

Call this method after opening a file directly via the underlying fileStream().

Definition at line 149 of file passwordfile.cpp.

## ◆ openOptions()

PasswordFileOpenFlags Io::PasswordFile::openOptions | ( |  | ) | const
| inline

Returns the options used to open the file.

Definition at line 210 of file passwordfile.h.

## ◆ password()

const std::string & Io::PasswordFile::password | ( |  | ) | const
| inline

Returns the current password.

It will be used when loading or saving using encryption.

Definition at line 126 of file passwordfile.h.

## ◆ path()

const std::string & Io::PasswordFile::path | ( |  | ) | const
| inline

Returns the current file path.

Definition at line 109 of file passwordfile.h.

## ◆ rootEntry() [1/2]

NodeEntry * Io::PasswordFile::rootEntry | ( |  | ) |

Returns the root entry if present or nullptr otherwise.

Definition at line 778 of file passwordfile.cpp.

## ◆ rootEntry() [2/2]

const NodeEntry * Io::PasswordFile::rootEntry | ( |  | ) | const

Returns the root entry if present or nullptr otherwise.

Definition at line 770 of file passwordfile.cpp.

## ◆ save()

void Io::PasswordFile::save | ( | PasswordFileSaveFlags | options = PasswordFileSaveFlags::Default | ) |

Writes the current root entry to the file under path() replacing its previous contents.

Parameters

  options | Specify the features (like encryption and compression) to be used.

Exceptions

  Throws | std::ios_base::failure when an IO error occurs.
  Throws | std::filesystem::filesystem_error when a filesystem error occurs.
  Throws | Io::CryptoException when an encryption error occurs.
  Throws | std::runtime_error when no root entry is present or a compression error occurs.

Definition at line 457 of file passwordfile.cpp.

## ◆ saveOptions()

PasswordFileSaveFlags Io::PasswordFile::saveOptions | ( |  | ) | const
| inline

Returns the save options used the last time when saving the file.

Definition at line 218 of file passwordfile.h.

## ◆ setPassword() [1/2]

void Io::PasswordFile::setPassword | ( | const char * | password,
|  | const std::size_t | passwordSize )

## ◆ setPassword() [2/2]

void Io::PasswordFile::setPassword | ( | const std::string & | password | ) |
| inline

Sets the current password.

It will be used when loading an encrypted file or when saving using encryption.

Definition at line 134 of file passwordfile.h.

## ◆ setPath()

void Io::PasswordFile::setPath | ( | const std::string & | value | ) |

Sets the current file path.

Closes the file if currently opened.

Definition at line 797 of file passwordfile.cpp.

## ◆ size()

size_t Io::PasswordFile::size | ( |  | ) |

Returns the size of the file if the file is open; otherwise returns zero.

Definition at line 839 of file passwordfile.cpp.

## ◆ summary()

string Io::PasswordFile::summary | ( | PasswordFileSaveFlags | saveOptions | ) | const

Returns a summary about the file (version, used features, statistics).

Definition at line 851 of file passwordfile.cpp.

## ◆ version()

std::uint32_t Io::PasswordFile::version | ( |  | ) | const
| inline

Returns the file version used the last time when saving the file (the version of the file as it is on the disk).

Remarks
  The version might change when re-saving with different options. See mininumVersion().

Definition at line 202 of file passwordfile.h.

## ◆ write()

void Io::PasswordFile::write | ( | PasswordFileSaveFlags | options = PasswordFileSaveFlags::Default | ) |

Writes the current root entry to the file which is assumed to be opened and writeable.

Parameters

  options | Specify the features (like encryption and compression) to be used.

Exceptions

  Throws | std::ios_base::failure when an IO error occurs.
  Throws | Io::CryptoException when an encryption error occurs.
  Throws | std::runtime_error when no root entry is present, a compression error occurs.

Definition at line 503 of file passwordfile.cpp.

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

- io/passwordfile.h
- io/passwordfile.cpp