Abstract base class for password store operations. More...

#include <pass.h>

Inheritance diagram for Pass:

Collaboration diagram for Pass:

Classes
struct	RecipientsForEditing
	What a dialog may do with the list of a folder (recipientsForEditing()). More...

Signals
void	idle ()
	Nothing of the store's runs or waits any more (isIdle()).
void	startingExecuteWrapper ()
	Emitted each time a queued process is about to start, and by the refusals that go on to emit processErrorExit().
void	statusMsg (const QString &msg, int timeout)
	Progress or a non-fatal problem worth a line in the status bar ("Creating backup commit", "Git pull failed: ...").
void	critical (const QString &title, const QString &message)
	Something went wrong that the user has to be told about in a dialog, such as a refused path or a failed backup commit.
void	processErrorExit (int exitCode, const QString &err)
	An operation ended in failure: its process exited non-zero, could not be started or crashed, or the operation was refused.
void	finishedAnyWithPid (const QString &out, const QString &err, Enums::PROCESS pid)
	A process of any kind finished successfully and its output cannot contain a secret.
void	finishedGitInit (const QString &out, const QString &err)
	git init in the store succeeded; the store is a repository now and the tree is re-read.
void	finishedGitPull (const QString &out, const QString &err)
	git pull succeeded; entries may have changed on disk.
void	finishedGitPush (const QString &out, const QString &err)
	git push succeeded.
void	finishedShow (const QString &out, const QString &file)
	Emitted when a Show() succeeds.
void	finishedInsert (const QString &out, const QString &err)
	An Insert() succeeded: the entry is in the store and, with Git in use, committed.
void	finishedRemove (const QString &out, const QString &err)
	A Remove() succeeded; the entry or folder is gone from the store.
void	finishedInit (const QString &out, const QString &err)
	An Init() succeeded: the folder's .gpg-id holds the new recipient list.
void	finishedMove (const QString &out, const QString &err)
	A Move() succeeded; the entry or folder is under its new name.
void	finishedCopy (const QString &out, const QString &err)
	A Copy() succeeded; the copy exists beside the original.
void	finishedGenerateGPGKeys (const QString &out, const QString &err)
	GenerateGPGKeys() succeeded; the new key pair is in the keyring.
void	generateGPGKeysFailed (const QString &err)
	Emitted when GPG key generation fails, alongside the generic processErrorExit(); lets the keygen dialog react to its own failure only, not to any other command failing meanwhile.
void	insertFailed (const QString &err, bool written)
	Emitted when an Insert() fails through a queued command, before the generic processErrorExit(): the process exited non-zero, crashed or could not be started, or the entry could not be put in place afterwards. Lets the password dialog keep what was typed and say why, without reacting to any other command failing meanwhile. An insert refused before anything is queued does not emit it.
void	finishedGrep (const QList< QPair< QString, QStringList > > &results)
	The newest Grep() is over; an empty list means no entry matched.

Public Member Functions
	Pass ()
	Construct a Pass instance.
void	init (const AppSettings &settings)
	Initialize the Pass instance with a settings snapshot.
virtual void	GitInit ()=0
	Initialize Git repository in password store.
virtual void	GitPull ()=0
	Pull changes from remote Git repository.
virtual void	GitPull_b ()=0
	Pull with rebase from remote.
virtual void	GitPush ()=0
	Push changes to remote Git repository.
virtual void	Show (QString file)=0
	Show decrypted password file.
virtual void	Insert (QString file, QString value, bool force)=0
	Insert or update password.
auto	insertsPending () const -> int
	How many inserts have started queueing but not yet reported.
virtual void	Remove (QString file, bool isDir)=0
	Remove password file or directory.
virtual void	Move (const QString srcDir, const QString dest, const bool force)=0
	Move password file or directory.
virtual void	Copy (const QString srcDir, const QString dest, const bool force)=0
	Copy password file or directory.
virtual void	Init (QString path, const QList< UserInfo > &users)=0
	Initialize new password store.
virtual void	Grep (QString pattern, bool caseInsensitive)=0
	Search password content for a pattern.
virtual auto	generatePassword (unsigned int length, const QString &charset) -> QString
	Generate random password.
void	GenerateGPGKeys (QString batch)
	Generate GPG keys using batch script.
auto	listKeys (QStringList keystrings, bool secret=false) -> QList< UserInfo >
	List GPG keys matching patterns.
auto	listKeys (const QString &keystring="", bool secret=false) -> QList< UserInfo >
	List GPG keys.
void	updateEnv ()
	Update environment for subprocesses.
auto	recipientsForEditing (const QString &dir, const QString &passStore) -> RecipientsForEditing
	The recipients a dialog may preselect for editing the list of `dir`.
auto	isIdle () const -> bool
	Whether no gpg, git or pass of this backend runs or waits.

Static Public Member Functions
static bool	gpgSupportsEd25519 (const QString &gpgExecutable={})
	Check if GPG supports Ed25519 encryption.
static QString	getDefaultKeyTemplate (const QString &gpgExecutable={})
	Get default key template for new GPG keys.
static auto	maxOutputArgs () -> QStringList
	The gpg options that enforce kMaxPlaintextBytes.
static auto	resolveGpgconfCommand (const QString &gpgPath) -> ResolvedGpgconfCommand
	Resolve the gpgconf command to kill agents.
static auto	getGpgIdPath (const QString &for_file, const QString &passStore) -> QString
	Get .gpg-id file path for a password file.
static auto	skippedGpgId (const QString &forFile, const QString &passStore, QString *recordError=nullptr) -> std::optional< QString >
	The folder list getGpgIdPath() passed over on its way up to the one it returns, if it passed one over that a signed store must not.
static auto	getRecipientList (const QString &for_file, const QString &passStore) -> QStringList
	Get list of recipients for a password file.
static auto	parseRecipients (const QByteArray &contents, const QString &sourceName) -> QStringList
	Parse the contents of a .gpg-id: one recipient per line, # starts a comment, unusable lines are logged and skipped.
static auto	loggableArgs (const QStringList &args) -> QStringList
	The arguments as they may appear in the debug log: the value of --passphrase and friends, and otpauth URIs, are replaced.
static auto	seedGpgIdFile (const QString &newDir, const QString &passStore) -> bool
	Seed a new folder's .gpg-id from the recipients it inherits.

Static Public Attributes
static constexpr qint64	kMaxPlaintextBytes = 64LL * 1024 * 1024
	Most bytes of plaintext a gpg decryption may produce.

Protected Types
enum class	LinkScope { EntryAndParents , ParentsOnly }
	What refuseLinkedPath() judges. More...
enum class	PathSpelling { Configured , PlacedByCaller }
	How a path handed to refuseLinkedPath() is spelled. More...
using	PROCESS = Enums::PROCESS
	Alias for Enums::PROCESS used throughout this class.

Protected Slots
virtual void	finished (int id, int exitCode, const QString &out, const QString &err)
	Handle process completion.

Protected Member Functions
auto	storeEnvironment () const -> QProcessEnvironment
	The environment QtPass runs the store's processes in.
auto	withCurrentGitPin (QProcessEnvironment base) const -> QProcessEnvironment
	`base` with GIT_DIR and GIT_WORK_TREE as the store is now (Util::gitStoreVariables()), not as it was at updateEnv(): a .git that appeared or changed hands since then is judged when Git runs.
auto	refuseSkippedGpgId (const QString &file, bool signing, const QString &except=QString()) -> bool
	With signing on, refuse to encrypt `file` when the lookup passed over its folder's own list (skippedGpgId()): the parent's list is not what was signed for it.
auto	verifySignedList (const GpgIdSigner &signer, const QString &gpgIdFile, QByteArray contents, QString why) const -> bool
	Whether `gpgIdFile` is a signed list QtPass accepts: its signature verifies (GpgIdSigner::verifyFile()), and it is current and bound to the folder it lies in (GpgIdGeneration::accept()), so an older authentic list put back, or one signed for another folder, is refused.
virtual auto	insertWritten (const QString &err) const -> bool
	Whether the insert that just failed had put its entry in the store before a later step failed. The backend that writes the entry knows; this default says no.
void	queueShow (const QString &file)
	Remember what a Show() asked for, so its completion can say so.
void	queueInsert ()
	Count one insert that has started queueing but not yet reported.
auto	refuseLinkedPath (const QString &path, LinkScope scope=LinkScope::EntryAndParents, PathSpelling spelling=PathSpelling::Configured) -> bool
	Refuse an operation on something that is, or lies behind, a symbolic link or NTFS junction inside the store.
auto	refuseFolderOutsideStore (const QString &folder, QString *relative=nullptr) -> bool
	Refuse recipients for a folder outside the store, as pass refuses a path with .. in it.
virtual auto	storeGit (const QStringList &args, QString *out) -> bool
	Run a git command in the store's repository, blocking.
auto	refuseUnfinishedGitOperation () -> bool
	Refuse to change the store while git is mid-rebase, -merge, -cherry-pick or -revert.
auto	unfinishedGitOperationReason () -> QString
	The unfinished git operation in progress in the store, if any.
auto	refusePendingPull () -> bool
	Refuse a store change while a Git pull is still queued or running.
void	executeWrapper (PROCESS id, const QString &app, const QStringList &args, bool readStdout=true, bool readStderr=true)
	Execute external wrapper command.
auto	generateRandomPassword (const QString &charset, unsigned int length) -> QString
	Generate random password from charset.
auto	boundedRandom (quint32 bound) -> quint32
	Generate random number in range.
void	setEnvVar (const QString &name, const QString &value)
	Set or remove an environment variable.
void	executeWrapper (PROCESS id, const QString &app, const QStringList &args, QString input, bool readStdout, bool readStderr)
	Execute wrapper with input.
virtual void	beforeExecute (PROCESS id)
	Hook invoked just before a wrapped command is dispatched.

Protected Attributes
AppSettings	m_settings
	Application settings snapshot injected at init() time.
Executor	exec
	Internal command executor for queuing and running subprocesses.

Private Member Functions
void	handleProcessError (PROCESS pid, int exitCode, const QString &out, const QString &err)
	Report a process that exited non-zero; called by finished().
auto	formatInsertError (const QString &friendly, const QString &err) -> QString
	Put the translated reason for a failed insert above what gpg itself printed, leaving out the machine-readable [GNUPG:] lines.
void	emitProcessFinishedSignal (PROCESS pid, const QString &out, const QString &err)
	Emit the signals for a process that exited with 0; called by finished() for everything but PASS_SHOW.
void	refuseAsNotPartOfStore (const QString &why)
	Refuse an operation on something that is not part of the store.

Private Attributes
bool	wrapperRunning {false}
	Unused; kept from the time Pass tracked the running wrapper.
QProcessEnvironment	env
	The environment the store's processes run in: the system environment plus what updateEnv() sets (PASSWORD_STORE_ variables, GNUPGHOME, PATH additions, WSLENV). Read through storeEnvironment().
QQueue< QString >	m_pendingShows
	Files of the Show() calls still in flight, oldest first.
int	m_insertsPending = 0
	Inserts that have started queueing but not yet reported; see queueInsert.

Detailed Description

Abstract base class for password store operations.

Pass provides an abstraction layer for password management, supporting both the native 'pass' utility and gopass/imitation backends. It handles:

Password file operations (show, insert, remove, move, copy)
GPG key management and Git integration
OTP generation
Random password generation

Subclasses must implement Git and password operations.

Paths: the operations take a path relative to the store, or an absolute path spelled from the store as configured (passStore), as the store tree and the dialogs build them. The link checks, pass names and Git paths are worked out against that spelling. A path spelled through the target of a store root that is itself a link is not under the store as named. Init() places such a folder from its canonical path; the other operations would check only the entry itself for a link and give pass and Git ../ names, so callers must not hand one over. Resolving every link instead is no way out: a removal would then reach a link's target, not the link.

Definition at line 75 of file pass.h.

Member Typedef Documentation

◆ PROCESS

using Pass::PROCESS = Enums::PROCESS

protected

Alias for Enums::PROCESS used throughout this class.

Definition at line 126 of file pass.h.

Member Enumeration Documentation

◆ LinkScope

enum class Pass::LinkScope

strongprotected

What refuseLinkedPath() judges.

Enumerator
EntryAndParents	The entry itself and every folder above it in the store.
ParentsOnly	Only the folders above it: a removal unlinks a link and touches nothing behind it.

Definition at line 486 of file pass.h.

◆ PathSpelling

enum class Pass::PathSpelling

strongprotected

How a path handed to refuseLinkedPath() is spelled.

Enumerator
Configured	As the store is configured or relative to it, the class's path rule. A path spelled through the target of a linked store root is then logged as a warning, so tests catch a caller that hands one over.
PlacedByCaller	Through the target of a linked store root, by a caller that places such a folder itself (Init()): not logged.

Definition at line 496 of file pass.h.

Constructor & Destructor Documentation

◆ Pass()

Pass::Pass ( )

Construct a Pass instance.

Definition at line 61 of file pass.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

Member Function Documentation

◆ beforeExecute()

void Pass::beforeExecute ( PROCESS id )

protectedvirtual

Hook invoked just before a wrapped command is dispatched.

Default is a no-op; backends override it to wrap execution (e.g. ImitatePass registers a transaction). Keeps the dispatch surface a single non-virtual executeWrapper instead of an overridden one.

Parameters

id	Process identifier of the command about to run.

Reimplemented in ImitatePass.

Definition at line 156 of file pass.cpp.

Here is the caller graph for this function:

◆ boundedRandom()

auto Pass::boundedRandom ( quint32 bound ) -> quint32

protected

Generate random number in range.

Parameters

bound Upper bound (exclusive).

Returns: Random number.

Definition at line 1206 of file pass.cpp.

Here is the caller graph for this function:

◆ Copy()

virtual void Pass::Copy	(	const QString	srcDir,
		const QString	dest,
		const bool	force )

pure virtual

Copy password file or directory.

Parameters

srcDir	Source path.
dest	Destination path.
force	Overwrite existing.

Implemented in ImitatePass, and RealPass.

◆ critical

void Pass::critical	(	const QString &	title,
		const QString &	message )

signal

Something went wrong that the user has to be told about in a dialog, such as a refused path or a failed backup commit.

Says only what happened; it does not by itself mean an operation is over. Every failure reported through the command queue goes on to processErrorExit(), and so do some refusals. Other checks made before anything is queued, such as an entry that already exists or a recipient list that cannot be used, emit this signal and nothing else.

Parameters

title	Translated dialog title.
message	Translated description.

Here is the caller graph for this function:

◆ emitProcessFinishedSignal()

void Pass::emitProcessFinishedSignal	(	PROCESS	pid,
		const QString &	out,
		const QString &	err )

private

Emit the signals for a process that exited with 0; called by finished() for everything but PASS_SHOW.

finishedAnyWithPid() goes out only for a process whose output cannot hold a secret (Enums::processInfo()), then the signal of that kind of process (finishedGitPull() and so on), if it has one.

Parameters

pid	Which kind of process finished.
out	Its stdout.
err	Its stderr.

Definition at line 595 of file pass.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ executeWrapper() [1/2]

void Pass::executeWrapper	(	PROCESS	id,
		const QString &	app,
		const QStringList &	args,
		bool	readStdout = true,
		bool	readStderr = true )

protected

Execute external wrapper command.

Parameters

id	Process identifier.
app	Executable path.
args	Command arguments.
readStdout	Capture stdout.
readStderr	Capture stderr.

Definition at line 113 of file pass.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ executeWrapper() [2/2]

void Pass::executeWrapper	(	PROCESS	id,
		const QString &	app,
		const QStringList &	args,
		QString	input,
		bool	readStdout,
		bool	readStderr )

protected

Execute wrapper with input.

Parameters

id	Process identifier.
app	Executable path.
args	Command arguments.
input	Input to pass to stdin.
readStdout	Capture stdout.
readStderr	Capture stderr.

Definition at line 119 of file pass.cpp.

Here is the call graph for this function:

◆ finished

void Pass::finished	(	int	id,
		int	exitCode,
		const QString &	out,
		const QString &	err )

protectedvirtualslot

Handle process completion.

Parameters

id	Process identifier.
exitCode	Process exit code.
out	Standard output.
err	Standard error.

Reimplemented in ImitatePass, and RealPass.

Definition at line 523 of file pass.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ finishedAnyWithPid

void Pass::finishedAnyWithPid	(	const QString &	out,
		const QString &	err,
		Enums::PROCESS	pid )

signal

A process of any kind finished successfully and its output cannot contain a secret.

Feeds the process output panel. Processes whose output may hold a decrypted entry (Enums::processInfo()) never emit it, so a receiver may log or display out and err as they are.

Parameters

out	Standard output from the process.
err	Standard error from the process.
pid	Which kind of process it was.

Here is the caller graph for this function:

◆ finishedCopy

void Pass::finishedCopy	(	const QString &	out,
		const QString &	err )

signal

A Copy() succeeded; the copy exists beside the original.

Parameters

out	Standard output.
err	Standard error.

Here is the caller graph for this function:

◆ finishedGenerateGPGKeys

void Pass::finishedGenerateGPGKeys	(	const QString &	out,
		const QString &	err )

signal

GenerateGPGKeys() succeeded; the new key pair is in the keyring.

The key generation dialog closes on it. A failure emits generateGPGKeysFailed() instead.

Parameters

out	Standard output.
err	Standard error.

Here is the caller graph for this function:

◆ finishedGitInit

void Pass::finishedGitInit	(	const QString &	out,
		const QString &	err )

signal

git init in the store succeeded; the store is a repository now and the tree is re-read.

Parameters

out	Standard output.
err	Standard error.

Here is the caller graph for this function:

◆ finishedGitPull

void Pass::finishedGitPull	(	const QString &	out,
		const QString &	err )

signal

git pull succeeded; entries may have changed on disk.

Parameters

out	Standard output.
err	Standard error.

Here is the caller graph for this function:

◆ finishedGitPush

void Pass::finishedGitPush	(	const QString &	out,
		const QString &	err )

signal

git push succeeded.

Parameters

out	Standard output.
err	Standard error.

Here is the caller graph for this function:

◆ finishedGrep

void Pass::finishedGrep ( const QList< QPair< QString, QStringList > > & results )

signal

The newest Grep() is over; an empty list means no entry matched.

Comes from NativeGrep on both backends and bypasses finished(), since the matching lines are decrypted content. A search superseded by a newer one never reports.

Parameters

results List of (entry path, matching lines) pairs.

Here is the caller graph for this function:

◆ finishedInit

void Pass::finishedInit	(	const QString &	out,
		const QString &	err )

signal

An Init() succeeded: the folder's .gpg-id holds the new recipient list.

Parameters

out	Standard output.
err	Standard error.

Here is the caller graph for this function:

◆ finishedInsert

void Pass::finishedInsert	(	const QString &	out,
		const QString &	err )

signal

An Insert() succeeded: the entry is in the store and, with Git in use, committed.

In ImitatePass this ends the whole transaction (gpg, then git add and commit), not just the gpg step. The password dialog closes on it. A failure reported through the command queue goes out as insertFailed() and processErrorExit() instead; an insert refused before anything is queued emits neither this signal nor insertFailed().

Parameters

out	Standard output of the operation's processes.
err	Standard error.

Here is the caller graph for this function:

◆ finishedMove

void Pass::finishedMove	(	const QString &	out,
		const QString &	err )

signal

A Move() succeeded; the entry or folder is under its new name.

Parameters

out	Standard output.
err	Standard error.

Here is the caller graph for this function:

◆ finishedRemove

void Pass::finishedRemove	(	const QString &	out,
		const QString &	err )

signal

A Remove() succeeded; the entry or folder is gone from the store.

Parameters

out	Standard output.
err	Standard error.

Here is the caller graph for this function:

◆ finishedShow

void Pass::finishedShow	(	const QString &	out,
		const QString &	file )

signal

Emitted when a Show() succeeds.

Requests complete in the order they were queued, so file is the argument of the Show() this result belongs to. Every receiver checks it against what it asked for; a failed decrypt emits processErrorExit() instead and never finishedShow().

Parameters

out	Decrypted password file content.
file	The Show() argument this content is for.

Here is the caller graph for this function:

◆ formatInsertError()

auto Pass::formatInsertError	(	const QString &	friendly,
		const QString &	err ) -> QString

private

Put the translated reason for a failed insert above what gpg itself printed, leaving out the machine-readable [GNUPG:] lines.

Parameters

friendly	Message from gpgErrorMessage().
err	gpg's stderr.

Returns: friendly, followed by the human-readable rest of err when there is any.

Definition at line 582 of file pass.cpp.

Here is the caller graph for this function:

◆ GenerateGPGKeys()

void Pass::GenerateGPGKeys ( QString batch )

Generate GPG keys using batch script.

Parameters

batch GPG batch script content.

Definition at line 394 of file pass.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ generateGPGKeysFailed

void Pass::generateGPGKeysFailed ( const QString & err )

signal

Emitted when GPG key generation fails, alongside the generic processErrorExit(); lets the keygen dialog react to its own failure only, not to any other command failing meanwhile.

Parameters

err	What gpg (or the setup) reported.

Here is the caller graph for this function:

◆ generatePassword()

auto Pass::generatePassword	(	unsigned int	length,
		const QString &	charset ) -> QString

virtual

Generate random password.

Parameters

length	Password length.
charset	Character set to use.

Returns: Generated password.

Definition at line 218 of file pass.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ generateRandomPassword()

auto Pass::generateRandomPassword	(	const QString &	charset,
		unsigned int	length ) -> QString

protected

Generate random password from charset.

Parameters

charset	Character set.
length	Password length.

Returns: Generated password.

Definition at line 1223 of file pass.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ getDefaultKeyTemplate()

QString Pass::getDefaultKeyTemplate ( const QString & gpgExecutable = {} )

static

Get default key template for new GPG keys.

Parameters

gpgExecutable Path to the gpg binary (defaults to "gpg").

Returns: Default template string.

Definition at line 291 of file pass.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ getGpgIdPath()

auto Pass::getGpgIdPath	(	const QString &	for_file,
		const QString &	passStore ) -> QString

static

Get .gpg-id file path for a password file.

Parameters

for_file	Path to password file.
passStore	Root directory of the password store.

Returns: Path to .gpg-id file.

Definition at line 920 of file pass.cpp.

Here is the caller graph for this function:

◆ getRecipientList()

auto Pass::getRecipientList	(	const QString &	for_file,
		const QString &	passStore ) -> QStringList

static

Get list of recipients for a password file.

Parameters

for_file	Path to password file.
passStore	Root directory of the password store.

Returns: List of recipient key IDs.

Definition at line 1146 of file pass.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ GitInit()

virtual void Pass::GitInit ( )

pure virtual

Initialize Git repository in password store.

Implemented in ImitatePass, and RealPass.

◆ GitPull()

virtual void Pass::GitPull ( )

pure virtual

Pull changes from remote Git repository.

Implemented in ImitatePass, and RealPass.

◆ GitPull_b()

virtual void Pass::GitPull_b ( )

pure virtual

Pull with rebase from remote.

Implemented in ImitatePass, and RealPass.

◆ GitPush()

virtual void Pass::GitPush ( )

pure virtual

Push changes to remote Git repository.

Implemented in ImitatePass, and RealPass.

◆ gpgSupportsEd25519()

bool Pass::gpgSupportsEd25519 ( const QString & gpgExecutable = {} )

static

Check if GPG supports Ed25519 encryption.

Parameters

gpgExecutable Path to the gpg binary (defaults to "gpg").

Returns: true if Ed25519 is supported.

Definition at line 273 of file pass.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ Grep()

virtual void Pass::Grep	(	QString	pattern,
		bool	caseInsensitive )

pure virtual

Search password content for a pattern.

Both backends decrypt each entry with gpg and match it in-process (NativeGrep), never through pass grep, so the pattern is one dialect for both: QRegularExpression, Perl-compatible (PCRE).

Parameters

pattern	Search pattern, a Perl-compatible regular expression.
caseInsensitive	true for case-insensitive search.

Implemented in ImitatePass, and RealPass.

Here is the call graph for this function:

◆ handleProcessError()

void Pass::handleProcessError	(	PROCESS	pid,
		int	exitCode,
		const QString &	out,
		const QString &	err )

private

Report a process that exited non-zero; called by finished().

Always ends in processErrorExit(). A failed insert first emits insertFailed(), and critical() too when the entry was written and only a git step after it failed; failed key generation first emits generateGPGKeysFailed().

Parameters

pid	Which kind of process failed.
exitCode	Its exit code.
out	Its stdout; not used.
err	Its stderr, or the Executor's message for a failed start.

Definition at line 552 of file pass.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ idle

void Pass::idle ( )

signal

Nothing of the store's runs or waits any more (isIdle()).

Emitted when the command queue drains. The main window re-enables the profile selector on it: switching stores is held back while commands for the current one are still queued.

Here is the caller graph for this function:

◆ Init()

virtual void Pass::Init	(	QString	path,
		const QList< UserInfo > &	users )

pure virtual

Initialize new password store.

Parameters

path	Root of password store.
users	List of recipient GPG keys.

Implemented in ImitatePass, and RealPass.

Here is the caller graph for this function:

◆ init()

void Pass::init ( const AppSettings & settings )

Initialize the Pass instance with a settings snapshot.

Parameters

settings Application settings to use for this backend lifetime.

Definition at line 158 of file pass.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ Insert()

virtual void Pass::Insert	(	QString	file,
		QString	value,
		bool	force )

pure virtual

Insert or update password.

Parameters

file	Path to password file.
value	Password content to store.
force	Overwrite existing file.

Implemented in ImitatePass, and RealPass.

Here is the caller graph for this function:

◆ insertFailed

void Pass::insertFailed	(	const QString &	err,
		bool	written )

signal

Emitted when an Insert() fails through a queued command, before the generic processErrorExit(): the process exited non-zero, crashed or could not be started, or the entry could not be put in place afterwards. Lets the password dialog keep what was typed and say why, without reacting to any other command failing meanwhile. An insert refused before anything is queued does not emit it.

Parameters

err	What gpg, pass or the placement of the entry reported.
written	true when this insert did put the entry in the store and only a later step (git add or commit) failed.

Here is the caller graph for this function:

◆ insertsPending()

auto Pass::insertsPending ( ) const -> int

inlinenodiscard

How many inserts have started queueing but not yet reported.

One Insert() still in the command queue, or running, counts here until its PASS_INSERT result goes out. A PasswordDialog reads this just before its own Insert() so it can tell an earlier insert's report (which it is also connected to, once a hanging queue let it open while its save was still pending) from its own.

Returns: The number of inserts awaiting their report.

Definition at line 194 of file pass.h.

Here is the caller graph for this function:

◆ insertWritten()

virtual auto Pass::insertWritten ( const QString & err ) const -> bool

inlinenodiscardprotectedvirtual

Whether the insert that just failed had put its entry in the store before a later step failed. The backend that writes the entry knows; this default says no.

Parameters

err	What the failed insert reported on stderr.

Returns: true when the failed insert's entry was written.

Reimplemented in ImitatePass, and RealPass.

Definition at line 461 of file pass.h.

Here is the caller graph for this function:

◆ isIdle()

auto Pass::isIdle ( ) const -> bool

inlinenodiscard

Whether no gpg, git or pass of this backend runs or waits.

Returns: true when its executor is idle.

Definition at line 423 of file pass.h.

Here is the call graph for this function:

◆ listKeys() [1/2]

auto Pass::listKeys	(	const QString &	keystring = "",
		bool	secret = false ) -> QList< UserInfo >

List GPG keys.

Parameters

keystring	Search pattern.
secret	Include secret keys.

Returns: List of matching keys.

Definition at line 442 of file pass.cpp.

Here is the call graph for this function:

◆ listKeys() [2/2]

auto Pass::listKeys	(	QStringList	keystrings,
		bool	secret = false ) -> QList< UserInfo >

List GPG keys matching patterns.

Parameters

keystrings	List of search patterns.
secret	Include secret keys.

Returns: List of matching keys.

Definition at line 426 of file pass.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ loggableArgs()

auto Pass::loggableArgs ( const QStringList & args ) -> QStringList

static

The arguments as they may appear in the debug log: the value of --passphrase and friends, and otpauth URIs, are replaced.

Parameters

args	The argv about to be run.

Returns: The same list with secret-shaped values redacted.

Definition at line 128 of file pass.cpp.

Here is the caller graph for this function:

◆ maxOutputArgs()

auto Pass::maxOutputArgs ( ) -> QStringList

static

The gpg options that enforce kMaxPlaintextBytes.

Returns: "--max-output" and the limit, for a gpg decryption's arguments.

Definition at line 701 of file pass.cpp.

Here is the caller graph for this function:

◆ Move()

virtual void Pass::Move	(	const QString	srcDir,
		const QString	dest,
		const bool	force )

pure virtual

Move password file or directory.

Parameters

srcDir	Source path.
dest	Destination path.
force	Overwrite existing.

Implemented in ImitatePass, and RealPass.

◆ parseRecipients()

auto Pass::parseRecipients	(	const QByteArray &	contents,
		const QString &	sourceName ) -> QStringList

static

Parse the contents of a .gpg-id: one recipient per line, # starts a comment, unusable lines are logged and skipped.

Parameters

contents	The file's bytes.
sourceName	Where they came from, for the log.

Returns: The recipient key IDs in file order.

Definition at line 1161 of file pass.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ processErrorExit

void Pass::processErrorExit	(	int	exitCode,
		const QString &	err )

signal

An operation ended in failure: its process exited non-zero, could not be started or crashed, or the operation was refused.

The counterpart of the finished... signals for an operation that queued a command: it ends in one or the other. The main window releases the busy state and shows err in the password pane. One case emits both: when RealPass has removed a linked folder but could not commit that, this signal is followed by finishedRemove(), because the store did change.

Before anything is queued the paths differ, so a caller must not wait for this signal after every call. A path behind a link and an unfinished Git operation are refused with startingExecuteWrapper(), critical() and this signal. Other early checks, such as an entry that already exists, emit critical() alone and return.

insertFailed() and generateGPGKeysFailed() are emitted before this signal whenever their operation fails through a queued command, be it a non-zero exit, a crash or a process that could not be started, so their dialogs need not guess whose failure it is. generateGPGKeysFailed() also comes first when no gpg executable is configured and nothing is queued at all. A refusal that reaches this signal without queuing anything emits neither of them.

Parameters

exitCode	Exit code of the process; -1 when it did not exit normally, 1 for a refusal.
err	What to show the user: stderr, or a translated message.

Here is the caller graph for this function:

◆ queueInsert()

void Pass::queueInsert ( )

inlineprotected

Count one insert that has started queueing but not yet reported.

Backends call this where Insert() queues its work, past every refusal; Pass::finished() counts it off again when the insert reports. Each queued insert reports once, as a PASS_INSERT, so the count tracks the inserts in flight. A dialog reads insertsPending() before its own Insert() to learn how many earlier reports are not its own.

Definition at line 484 of file pass.h.

Here is the caller graph for this function:

◆ queueShow()

void Pass::queueShow ( const QString & file )

inlineprotected

Remember what a Show() asked for, so its completion can say so.

Backends call this first thing in Show(); Pass::finished() pops the entry again on success or failure. The Executor runs one queue in order, so the two stay aligned.

Parameters

file	The Show() argument.

Definition at line 474 of file pass.h.

Here is the caller graph for this function:

◆ recipientsForEditing()

auto Pass::recipientsForEditing	(	const QString &	dir,
		const QString &	passStore ) -> RecipientsForEditing

The recipients a dialog may preselect for editing the list of dir.

With a signing key configured, only a list whose signature, generation and folder binding are all accepted: the Users dialog preselects what it loads and OK writes and signs the selection, so a list read unauthenticated would turn an attacker's unsigned edit into a genuinely signed one with one click. The one exception is an authentic list the generation record calls older (the recovery from a rollback goes through this dialog): preselected, with the reason shown for review. Anything else that fails preselects nothing and says why. Without a signing key, the list as it is.

Parameters

dir	Folder whose list is edited; empty for the store root.
passStore	The store the folder belongs to: the dialog's, which for a profile being set up is not this backend's.

Returns: The state, the recipients to preselect and the warning to show.

Definition at line 1068 of file pass.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ refuseAsNotPartOfStore()

void Pass::refuseAsNotPartOfStore ( const QString & why )

private

Refuse an operation on something that is not part of the store.

Emits startingExecuteWrapper(), critical() and processErrorExit(), so an interface that arms itself when an operation starts is released again although nothing was started. refuseLinkedPath() and refuseFolderOutsideStore() say why.

Parameters

why	Translated reason, shown to the user.

Definition at line 912 of file pass.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ refuseFolderOutsideStore()

auto Pass::refuseFolderOutsideStore	(	const QString &	folder,
		QString *	relative = nullptr ) -> bool

protected

Refuse recipients for a folder outside the store, as pass refuses a path with .. in it.

ImitatePass would write a .gpg-id that the store never reads, and pass init --path would take the folder's absolute path as a folder under the store. Links on the way are resolved, as for the store root.

Parameters

folder	The folder, absolute.
relative	Where the folder lies in the store, as PathValidator::storeRelativePath() gives it (empty for the root), when it is not refused; may be null.

Returns: true when critical() and processErrorExit() were emitted and the caller must stop.

Definition at line 819 of file pass.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ refuseLinkedPath()

auto Pass::refuseLinkedPath	(	const QString &	path,
		LinkScope	scope = LinkScope::EntryAndParents,
		PathSpelling	spelling = PathSpelling::Configured ) -> bool

protected

Refuse an operation on something that is, or lies behind, a symbolic link or NTFS junction inside the store.

The store tree shows a linked entry or folder like any other, and gpg, pass and QFile all follow links, so without this a planted link would have an entry shown, edited, copied or written outside the store, with the store's recipients. The configured store root itself may be a link (a synced folder); that is not judged.

Parameters

path	Store-relative (as Show/Insert/Remove get it, .gpg included where it applies) or absolute (as Move/Copy get it).
scope	Whether the entry itself counts, or only the folders it lies in (a removal).
spelling	Whether `path` follows the class's path rule, or the caller places a target-spelled path itself (Init()).

Returns: true when critical() and processErrorExit() were emitted and the caller must stop.

Definition at line 791 of file pass.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ refusePendingPull()

auto Pass::refusePendingPull ( ) -> bool

protected

Refuse a store change while a Git pull is still queued or running.

An operation checks the repository when it is requested, but a pull queued before it (the asynchronous Update) has not run yet, so a conflict it will cause is not visible. For operations that commit without a later point to re-check (every delete, move and copy, and the pass backend, whose single pass insert commits by itself), refuse while the pull is in flight so the change cannot land in the conflict it leaves. Nothing is refused when Git is off or no pull is pending.

Returns: true when critical() and processErrorExit() were emitted and the caller must stop.

Definition at line 883 of file pass.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ refuseSkippedGpgId()

auto Pass::refuseSkippedGpgId	(	const QString &	file,
		bool	signing,
		const QString &	except = QString() ) -> bool

protected

With signing on, refuse to encrypt file when the lookup passed over its folder's own list (skippedGpgId()): the parent's list is not what was signed for it.

Parameters

file	The entry or folder about to be encrypted to.
signing	Whether a signing key is set (signed lists in use).
except	A list about to be written (by pass init), which may be missing now without that being refused.

Returns: Whether it was refused (and the user told).

Definition at line 927 of file pass.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ refuseUnfinishedGitOperation()

auto Pass::refuseUnfinishedGitOperation ( ) -> bool

protected

Refuse to change the store while git is mid-rebase, -merge, -cherry-pick or -revert.

A pull that stopped in a conflict leaves the repository part-way through an operation. Committing a save or a re-encryption into it lands the change on a detached HEAD (a later git rebase --abort drops it) or concludes the merge in favour of the local copy (pushing over a colleague's change). Every store-changing operation calls this at its entry, next to refuseLinkedPath(), so the change is refused before gpg or pass runs and the dialog keeps what was typed. Nothing is refused when git is off, the store is not a repository, or git gives no answer. A HEAD detached by hand (no operation in progress) is deliberately accepted.

Returns: true when critical() and processErrorExit() were emitted and the caller must stop.

Definition at line 898 of file pass.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ Remove()

virtual void Pass::Remove	(	QString	file,
		bool	isDir )

pure virtual

Remove password file or directory.

Parameters

file	Path to remove.
isDir	true if removing a directory.

Implemented in ImitatePass, and RealPass.

◆ resolveGpgconfCommand()

auto Pass::resolveGpgconfCommand ( const QString & gpgPath ) -> ResolvedGpgconfCommand

static

Resolve the gpgconf command to kill agents.

Parameters

gpgPath Path to gpg executable.

Returns: Resolved command with program and arguments.

Definition at line 354 of file pass.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ seedGpgIdFile()

auto Pass::seedGpgIdFile	(	const QString &	newDir,
		const QString &	passStore ) -> bool

static

Seed a new folder's .gpg-id from the recipients it inherits.

Writes the recipient list that is in effect for newDir (found by walking up to the nearest parent .gpg-id, see getGpgIdPath) into newDir/.gpg-id atomically with owner-only permissions. Refuses to overwrite an existing .gpg-id and writes nothing when no recipient is inherited, so a zero-byte file never shadows the parent's list.

Parameters

newDir	Absolute path of the freshly created folder.
passStore	Root directory of the password store.

Returns: true when the file was written, false otherwise.

Definition at line 1182 of file pass.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ setEnvVar()

void Pass::setEnvVar	(	const QString &	name,
		const QString &	value )

protected

Set or remove an environment variable.

Parameters

name	Variable name (e.g. "PASSWORD_STORE_DIR"), no trailing '='.
value	New value; an empty string removes the variable entirely.

Definition at line 624 of file pass.cpp.

Here is the caller graph for this function:

◆ Show()

virtual void Pass::Show ( QString file )

pure virtual

Show decrypted password file.

Parameters

file	Path to password file relative to store root.

Implemented in ImitatePass, and RealPass.

Here is the caller graph for this function:

◆ skippedGpgId()

auto Pass::skippedGpgId	(	const QString &	forFile,
		const QString &	passStore,
		QString *	recordError = nullptr ) -> std::optional< QString >

static

The folder list getGpgIdPath() passed over on its way up to the one it returns, if it passed one over that a signed store must not.

getGpgIdPath() skips a .gpg-id that is missing, a link or a junction and falls back to a parent folder's list, as pass does. In a signed store that lets anyone who can write to it, without the signing key, move a folder's entries to the parent's (also validly signed) recipients by removing or linking the folder's own list. This names the first such list between the start and the folder of the list found (that folder and the store root excluded): one that is under the name but not a regular file, or one that is gone although this device has accepted a list at that path before (GpgIdGeneration::remembered()). When the generation record cannot be read, whether a list was accepted at a path cannot be told: the first folder without its own list is named then too (fail closed), and recordError says why.

Parameters

forFile	Entry or folder, as for getGpgIdPath().
passStore	Root directory of the password store.
recordError	Receives the record's error when it could not be read, if not null; left untouched otherwise.

Returns: The skipped .gpg-id path, or nothing when the list found is the one that applies.

Definition at line 982 of file pass.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ startingExecuteWrapper

void Pass::startingExecuteWrapper ( )

signal

Emitted each time a queued process is about to start, and by the refusals that go on to emit processErrorExit().

The main window shows the busy state on it. An operation made of several processes emits it once per process; the operation then ends with a finished... signal or with processErrorExit().

Here is the caller graph for this function:

◆ statusMsg

void Pass::statusMsg	(	const QString &	msg,
		int	timeout )

signal

Progress or a non-fatal problem worth a line in the status bar ("Creating backup commit", "Git pull failed: ...").

Nothing depends on it being shown; an error the user must see goes out as critical() instead.

Parameters

msg	Translated status text.
timeout	How long to show it, in milliseconds.

Here is the caller graph for this function:

◆ storeEnvironment()

auto Pass::storeEnvironment ( ) const -> QProcessEnvironment

inlinenodiscardprotected

The environment QtPass runs the store's processes in.

What updateEnv() made: the git ceiling and the PASSWORD_STORE_ variables QtPass's own environment does not carry. For blocking calls that start their own process.

Returns: A copy of the environment.

Definition at line 96 of file pass.h.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ storeGit()

virtual auto Pass::storeGit	(	const QStringList &	args,
		QString *	out ) -> bool

inlineprotectedvirtual

Run a git command in the store's repository, blocking.

The two backends reach git differently: ImitatePass runs the configured git with -C <Store tree and entries>, RealPass runs pass git. The default (no git) answers false. Used by refuseUnfinishedGitOperation() to ask the repository its state before an operation changes the store.

Parameters

args	The git arguments (without the executable or -C).
out	Receives the command's standard output; may be null.

Returns: true when git ran and exited 0, false otherwise (git off, the store is not a repository, or git failed).

Reimplemented in ImitatePass, and RealPass.

Definition at line 560 of file pass.h.

Here is the caller graph for this function:

◆ unfinishedGitOperationReason()

auto Pass::unfinishedGitOperationReason ( ) -> QString

protected

The unfinished git operation in progress in the store, if any.

The detection behind refuseUnfinishedGitOperation(), without emitting a refusal: a backend re-checks it when a save's gpg step has finished (a pull queued before the save, from the asynchronous Update, may have finished and left a conflict meanwhile) so the entry is not placed or committed into the operation.

Returns: A ready-to-show reason naming the operation (rebase, merge, cherry-pick or revert), or an empty string when none is in progress, git is off, or the store is not a repository.

Definition at line 835 of file pass.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ updateEnv()

void Pass::updateEnv ( )

Update environment for subprocesses.

Definition at line 631 of file pass.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ verifySignedList()

auto Pass::verifySignedList	(	const GpgIdSigner &	signer,
		const QString &	gpgIdFile,
		QByteArray *	contents,
		QString *	why ) const -> bool

protected

Whether gpgIdFile is a signed list QtPass accepts: its signature verifies (GpgIdSigner::verifyFile()), and it is current and bound to the folder it lies in (GpgIdGeneration::accept()), so an older authentic list put back, or one signed for another folder, is refused.

Parameters

signer	The verifier, with the configured signing keys.
gpgIdFile	The .gpg-id.
contents	Receives the verified bytes.
why	Receives why a current-and-bound check refused the list; left as it is when the signature itself does not verify.

Returns: Whether the list may be encrypted to.

Definition at line 963 of file pass.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ withCurrentGitPin()

auto Pass::withCurrentGitPin ( QProcessEnvironment base ) const -> QProcessEnvironment

nodiscardprotected

base with GIT_DIR and GIT_WORK_TREE as the store is now (Util::gitStoreVariables()), not as it was at updateEnv(): a .git that appeared or changed hands since then is judged when Git runs.

Parameters

base	The environment to update.

Returns: base, the two variables recomputed (left as they are when the store keeps to a parent repository or there is none).

Definition at line 687 of file pass.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

Member Data Documentation

◆ env

QProcessEnvironment Pass::env

private

The environment the store's processes run in: the system environment plus what updateEnv() sets (PASSWORD_STORE_ variables, GNUPGHOME, PATH additions, WSLENV). Read through storeEnvironment().

Definition at line 85 of file pass.h.

◆ exec

Executor Pass::exec

protected

Internal command executor for queuing and running subprocesses.

Definition at line 121 of file pass.h.

◆ kMaxPlaintextBytes

qint64 Pass::kMaxPlaintextBytes = 64LL * 1024 * 1024

staticconstexpr

Most bytes of plaintext a gpg decryption may produce.

An OpenPGP message is compressed, so a small entry in a shared store can decompress to gigabytes; gpg stops at this many (–max-output) instead of filling QtPass's memory. Far above any real entry.

Definition at line 277 of file pass.h.

◆ m_insertsPending

int Pass::m_insertsPending = 0

private

Inserts that have started queueing but not yet reported; see queueInsert.

Definition at line 681 of file pass.h.

◆ m_pendingShows

QQueue<QString> Pass::m_pendingShows

private

Files of the Show() calls still in flight, oldest first.

Definition at line 679 of file pass.h.

◆ m_settings

AppSettings Pass::m_settings

protected

Application settings snapshot injected at init() time.

Populated by init(AppSettings) and valid for the lifetime of this backend instance. Subclasses read it in place of calling QtPassSettings directly.

Definition at line 117 of file pass.h.

◆ wrapperRunning

bool Pass::wrapperRunning {false}

private

Unused; kept from the time Pass tracked the running wrapper.

Definition at line 79 of file pass.h.

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

src/pass.h
src/pass.cpp

Classes

Signals

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Types

Protected Slots

Protected Member Functions

Protected Attributes

Private Member Functions

Private Attributes

Detailed Description

Member Typedef Documentation

◆ PROCESS

Member Enumeration Documentation

◆ LinkScope

◆ PathSpelling

Constructor & Destructor Documentation

◆ Pass()

Member Function Documentation

◆ beforeExecute()

◆ boundedRandom()

◆ Copy()

◆ critical

◆ emitProcessFinishedSignal()

◆ executeWrapper() [1/2]

◆ executeWrapper() [2/2]

◆ finished

◆ finishedAnyWithPid

◆ finishedCopy

◆ finishedGenerateGPGKeys

◆ finishedGitInit

◆ finishedGitPull

◆ finishedGitPush

◆ finishedGrep

◆ finishedInit

◆ finishedInsert

◆ finishedMove

◆ finishedRemove

◆ finishedShow

◆ formatInsertError()

◆ GenerateGPGKeys()

◆ generateGPGKeysFailed

◆ generatePassword()

◆ generateRandomPassword()

◆ getDefaultKeyTemplate()

◆ getGpgIdPath()

◆ getRecipientList()

◆ GitInit()

◆ GitPull()

◆ GitPull_b()

◆ GitPush()

◆ gpgSupportsEd25519()

◆ Grep()

◆ handleProcessError()

◆ idle

◆ Init()

◆ init()

◆ Insert()

◆ insertFailed

◆ insertsPending()

◆ insertWritten()

◆ isIdle()

◆ listKeys() [1/2]

◆ listKeys() [2/2]

◆ loggableArgs()

◆ maxOutputArgs()

◆ Move()

◆ parseRecipients()

◆ processErrorExit

◆ queueInsert()

◆ queueShow()

◆ recipientsForEditing()

◆ refuseAsNotPartOfStore()

◆ refuseFolderOutsideStore()

◆ refuseLinkedPath()

◆ refusePendingPull()

◆ refuseSkippedGpgId()

◆ refuseUnfinishedGitOperation()

◆ Remove()