pashage

Documentation
Login

Documentation

Casual Maintenance Intended

pashage

Yet Another Opinionated Re-engineering of the Unix Password Store

Core objectives:

Portability is not a core objective, but a nice side-effect of using basic POSIX shell, and it is embraced when possible.

Security is not branded as a core objective, because the author does not have the clout to declare anything secure, and you should probably not trust random READMEs anyway. However the simplicity should help you assess whether this password store is a worthwhile trade-off for your threat model.

For the reference, the author has views similar to those of Filippo Valsorda and considers the password store shell script to be about as critical as the rest of her computer, and relies mostly on age to provide secure encryption at rest and on a YubiKey to gatekeep decryption.

Licencing

This project was written from scratch, and every character of the script was typed with my fingers. However I looked deeply into pass, passage, and pash code bases. I don't know whether that's enough to make it a derivative work covered by the GPL, so to be on the safe side I'm using GPL v2+ too.

Differences with pass

Behavior Differences

New Features and Extensions

Roadmap

The following features are currently under consideration:

Manual

pashage is a password manager, which means it manages a database of encrypted secrets, including encrypting externally-provided new secrets, generating and encrypting random strings, and decrypting and displaying stored secrets.

It aims to be simple and composable, but its reliance on Unix philosophy and customs might make steep learning curve for users outside of this culture.

It is used through a shell command, denoted as pashage in this document, immediately followed by a subcommand and its arguments. When no subcommand is specified, list or show is implicitly assumed.

The database is optionally versioned using git to help with history audit and synchronization. It should be noted that this prevents re-encryption from erasing old cyphertext, leaving the secret vulnerable to compromised encryption keys.

The cryptography is done by age external command. It decrypts using the identity file given in the environment, and crypts using a list of recipients per subfolder, defaulting to the parent recipient list or the identity.

Command Reference

Here is an alphabetical list of all subcommands and aliases:

copy

Syntax:

pashage copy [--reencrypt,-e | --interactive,-i | --keep,-k ]
             [--force,-f] old-path ... new-path

This subcommand copies secrets and recursively copies subfolders, using the same positional argument scheme as cp(1). By default it asks before overwriting an existing secret and it re-encrypts the secret when the destination has a different recipient list.

Flags:

Environment:

delete

Syntax:

pashage delete [--recursive,-r] [--force,-f] pass-name ...

This subcommand deletes secrets from the database. By default it skips subfolders and asks for confirmation for each secret.

Flags:

Environment:

edit

Syntax:

pashage edit pass-name ...

This subcommand starts an interactive editor to update the secrets.

Environment:

find

Syntax:

pashage find [GREP_OPTIONS] regex

This subcommand lists as a tree the secrets whose name match the given regular expression, using the corresponding grep(1) options.

Environment:

generate

Syntax:

pashage generate [--no-symbols,-n] [--clip,-c | --qrcode,-q]
                 [--in-place,-i | --force,-f] [--multiline,-m]
                 [--try,-t] pass-name [pass-length [character-set]]

This subcommand generates a new secret from /dev/urandom, stores it in the database, and by default displays it on the standard output and asks for confirmation before overwriting an existing secret.

Flags:

Environment:

git

Syntax:

pashage git git-command-args ...

This subcommand invokes git in the database repository. Only git init and git clone are accepted when there is no underlying repository.

Environment:

gitconfig

Syntax:

pashage gitconfig

This subcommand configures the underlying repository to automatically decrypt secrets to display differences.

Environment:

grep

Syntax:

pashage grep [GREP_OPTIONS] search-regex

This subcommand successively decrypts all the secrets in the store and filter them through grep(1) using the given options, and outputs all the matching lines and the corresponding secret.

Environment:

help

Syntax:

pashage help

This subcommand displays on the standard output the version and help text, including all subcommands and flags and a brief description.

This subcommand is not affected by the environment.

init

Syntax:

pashage init [--interactive,-i | --keep,-k ]
             [--path=subfolder,-p subfolder] age-recipient ...

This subcommand initializes an age recipient list, by default of the root of the password store, and re-encrypts all the affected secrets. When the recipient list is a single empty string, the recipient list is instead removed, falling back to a parent recipient list or ultimately to the age identity.

Flags:

Environment:

insert

Syntax:

pashage insert [--echo,-e | --multiline,-m] [--force,-f] pass-name ...

This subcommand adds new secrets in the database, using the provided data from the standard input. By default asks before overwriting an existing secret, and it reads a single secret line after turning off the console echo, and reads it a second time for confirmation.

Flags:

Environment:

list

Syntax:

pashage [list] [subfolder ...]

This subcommand displays the given subfolders as a tree, or the whole store when no subfolder is specified.

Note that when a secret is given instead of a subfolder, the show command will be used instead, without any warning or error.

Environment:

move

Syntax:

pashage move [--reencrypt,-e | --interactive,-i | --keep,-k ]
             [--force,-f] old-path ... new-path

This subcommand moves or renames secrets and subfolders recursively, using the same positional argument scheme as mv(1). By default it asks before overwriting an existing secret and it re-encrypts the secret when the destination has a different recipient list.

Flags:

Environment:

random

Syntax:

pashage random [pass-length [character-set]]

This subcommand generates a new secret, like the generate subcommand, then directly displays on the standard output without storing it.

Environment:

reencrypt

Syntax:

pashage reencrypt [--interactive,-i] pass-name|subfolder ...

This subcommand re-encrypts in place the given secrets, and all the secrets recursively in the given subfolders.

Flags:

Environment:

show

Syntax:

pashage [show] [--clip[=line-number],-c[line-number] |
                --qrcode[=line-number],-q[line-number]] pass-name ...

This subcommand decrypts the given secrets and by default displays the whole text on the standard output.

Note that when a subfolder is given instead of a secret, the list command will be used instead, without any warning or error.

Flags:

Environment:

version

Syntax:

pashage version

This subcommand displays on the standard output the version and author list.

This subcommand is not affected by the environment.