PASSAGE(1) Mutineer's Guide - passage PASSAGE(1)
NAME
passage - password store utilizing age for encryption
SYNOPSIS
passage convert [-v] [DIRECTORY]
passage cp [-fr] SOURCE DESTINATION
passage edit FILE...
passage generate [-f] [-l LENGTH] FILE
passage init
passage ln [-f] TARGET DESTINATION
passage mkdir [-p] DIRECTORY...
passage mv [-f] SOURCE DESTINATION
passage rm [-fr] FILE/DIRECTORY...
passage show [-c] [FILE/DIRECTORY...]
DESCRIPTION
passage is a password store. It allows for storing passwords within a
directory, by default ${XDG_DATA_HOME}/share/passage, encrypting them
with age(1). It is based on the design of pass(1), with deviation where
pass(1) seems inconsistent or prone to feature-creep.
Goals
• Usage of age(1) rather than gpg(1). This helps to reduce the
overall amount of cruft and bloat being used in cryptography
programs, and while it’s mostly a philosophical reason, it’s the
main reason this was written.
• POSIX sh(1) compatibility. pass(1) depends on bash(1), and uses
quite a lot of bashisms, making using it with other default system
shells require a lot of changes to the code. passage doesn’t have
any non-POSIX compatible requirements, aside from age(1).
• A preference of printing easily machine-readable content by
default. pass(1)'s output tends to be geared more towards
human-readability, which can occasionally be annoying for scripting
and automated usage.
• Avoidance of piece-meal operations on password files. Most password
editing operations, other than generating a new password, should
just be done through a text editor.
• Don’t automate much by default, and don’t duplicate functionality;
for example, this means that unlike pass(1), the generate command
does not copy to the clipboard with a switch, because show -c will
do that just fine. Directories are also not automatically created
when necessary.
• Conforming to XDG specifications by default. pass(1) does not,
though it can be made to.
COMMANDS
When providing a password file as an argument, do not include the
".age" suffix.
cp [-fr] SOURCE DESTINATION
Copy a password file or directory from SOURCE to DESTINATION. -f
will allow overwriting existing files. -r will copy a directory
recursively.
convert [-v] [DIRECTORY]
Convert a pass(1) password store, DIRECTORY to a passage(1) store.
All files are decrypted using gpg(1), and then reencrypted with
age(1). If -v is specified, the gpg(1)-encrypted files will be
listed to standard error as they are converted. If unspecified,
DIRECTORY is PASSWORD_STORE_DIR (which is ~/.password-store by
default).
edit FILE
Decrypt and open FILE in your editor. The decrypted file is written
to a temporary file with owner-only read and write permissions, and
then written back to the original location.
generate [-f] [-l LENGTH] FILE
Generate a password of LENGTH characters long to FILE. If a custom
LENGTH is unspecified, the default length is 24 characters long.
The password contains alphabetical, numeric, and punctuation
symbols. If the password file already exists, it will not overwrite
it. If -f is specified, it will.
init
Create the password store directory. No arguments are taken, as the
directory and keys (if not defaults) should be set in the config or
environment (see ENVIRONMENT and FILES) anyway.
ln [-f] TARGET DESTINATION
Create a symbolic link at DESTINATION that resolves to TARGET. -f
will allow overwriting existing files and links.
mkdir [-p] DIRECTORY...
Create a directory named DIRECTORY. -p will create all parents of
the directory if they do not exist.
mv [-f] SOURCE DESTINATION
Move the SOURCE file or directory to DESTINATION. -f will allow
overwriting files.
rm [-fr] FILE/DIRECTORY...
Delete a file/directory in the password store. -f will not error
out if the file or directory doesn’t exist. -r will remove a
directory recursively.
show [-c] [FILE/DIRECTORY...]
Show a list of password files and directories, or show the contents
of a password file. Directories are listed with a trailing slash
(/) at the end of a line, files are not. Files have their ".age"
suffix removed for readability. If a path to a password file is
given, the contents of that file are printed to standard output.
If -c is specified and a password file is given, the contents are
copied to your X clipboard using xsel(1), rather than being
printed, and then the clipboard is cleared after 45 seconds. If
you provide a path to a password directory, the directory is
listed. If you provide no path of any sort, the entire password
store is listed.
VARIABLES
These variables can be set in the configuration file (see FILES). If
they are in the environment, the environment variables will take
priority.
EDITOR
The default editor used by the edit command. If not set, it
defaults to vi(1).
PASSAGE_DIR
A directory containing the password store. If not specified,
${XDG_DATA_HOME}/passage is used instead.
PASSAGE_KEY
A file path. This is the key used for encrypting passwords; your
private key. If not specified, ${XDG_CONFIG_HOME}/passage/privkey
is used.
PASSAGE_RECIPIENTS
A file path. This is the list of public keys that password files
are encrypted for; as in, this is what public keys should be able
to decrypt password files. If not specified,
${XDG_CONFIG_HOME}/passage/recipients is used.
PASSWORD_STORE_DIR
If set, this directory is used by convert, rather than pass(1)'s
own default, ~/.password-store. It’s not used if you provide
directories as arguments to convert, though. This environment
variable is also used by pass(1), thus the reason it is used here.
FILES
${PASSAGE_DIR}/*.age
Files encrypted with age(1).
${XDG_DATA_HOME}/passage
The default location of the password store. The location can be
changed with PASSAGE_DIR. By default, XDG_DATA_HOME is set to
~/.local/share.
${XDG_CONFIG_HOME}/passage/passage.conf
The default location of the configuration. Any variable in
VARIABLES can be set here. By default XDG_CONFIG_HOME is set to
~/.config.
${XDG_CONFIG_HOME}/passage/privkey
The default location of the encrypting key, or private key. The
encrypting key can be changed with PASSAGE_KEY. By default
XDG_CONFIG_HOME is set to ~/.config.
${XDG_CONFIG_HOME}/passage/recipients
The default location of the recipients list. The location can be
changed with PASSAGE_RECIPIENTS. By default XDG_CONFIG_HOME is set
to ~/.config.
NOTES
Since age(1) supports using SSH public/private key pairs for encrypting
and decrypting, you can actually just set PASSAGE_KEY to ~/.ssh/id_rsa
(or similar) and PASSAGE_RECIPIENTS to ~/.ssh/id_rsa.pub (again, or
similar), and use your SSH keys for things.
CONTRIBUTING
The canonical URL of this repository is
<https://git.mutiny.red/somasis/passage>. Submit patches and bugs to
<[email protected]>.
There is also an IRC channel for passage and other projects at
<irc://irc.freenode.net/#mutiny>. Please don’t hesitate to message if
you need help.
LICENSE
passage is in the public domain.
To the extent possible under law, Kylie McClain has waived all
copyright and related or neighboring rights to this work.
<http://creativecommons.org/publicdomain/zero/1.0/>
passage 0 2020-06-26 PASSAGE(1)