aboutsummaryrefslogtreecommitdiff
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
       <kylie@somas.is>.

       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)