X-Git-Url: https://git.ucc.asn.au/?p=zanchey%2Fuccpass.git;a=blobdiff_plain;f=pass%2Fshare%2Fman%2Fman1%2Fpass.1;fp=pass%2Fshare%2Fman%2Fman1%2Fpass.1;h=e1fe6055ea235e01298b7b9c4d62a817df492ce7;hp=0000000000000000000000000000000000000000;hb=f262d810782904db38e059808bb6bad9bf63406a;hpb=2aa1d0afecaa8eee41ab24904bd735618094ccd4 diff --git a/pass/share/man/man1/pass.1 b/pass/share/man/man1/pass.1 new file mode 100644 index 0000000..e1fe605 --- /dev/null +++ b/pass/share/man/man1/pass.1 @@ -0,0 +1,450 @@ +.TH PASS 1 "2014 March 18" ZX2C4 "Password Store" + +.SH NAME +pass - stores, retrieves, generates, and synchronizes passwords securely + +.SH SYNOPSIS +.B pass +[ +.I COMMAND +] [ +.I OPTIONS +]... [ +.I ARGS +]... + +.SH DESCRIPTION + +.B pass +is a very simple password store that keeps passwords inside +.BR gpg2 (1) +encrypted files inside a simple directory tree residing at +.IR ~/.password-store . +The +.B pass +utility provides a series of commands for manipulating the password store, +allowing the user to add, remove, edit, synchronize, generate, and manipulate +passwords. + +If no COMMAND is specified, COMMAND defaults to either +.B show +or +.BR ls , +depending on the type of specifier in ARGS. Otherwise COMMAND must be one of +the valid commands listed below. + +Several of the commands below rely on or provide additional functionality if +the password store directory is also a git repository. If the password store +directory is a git repository, all password store modification commands will +cause a corresponding git commit. See the \fIEXTENDED GIT EXAMPLE\fP section +for a detailed description using \fBinit\fP and +.BR git (1). + +The \fBinit\fP command must be run before other commands in order to initialize +the password store with the correct gpg key id. Passwords are encrypting using +the gpg key set with \fBinit\fP. + +There is a corresponding bash completion script for use with tab completing +password names in +.BR bash (1). + +.SH COMMANDS + +.TP +\fBinit\fP [ \fI--path=sub-folder\fP, \fI-p sub-folder\fP ] \fIgpg-id...\fP +Initialize new password storage and use +.I gpg-id +for encryption. Multiple gpg-ids may be specified, in order to encrypt each +password with multiple ids. This command must be run first before a password +store can be used. If the specified \fIgpg-id\fP is different from the key +used in any existing files, these files will be reencrypted to use the new id. +Note that use of +.BR gpg-agent (1) +is recommended so that the batch decryption does not require as much user +intervention. If \fI--path\fP or \fI-p\fP is specified, along with an argument, +a specific gpg-id or set of gpg-ids is assigned for that specific sub folder of +the password store. If only one \fIgpg-id\fP is given, and it is an empty string, +then the current \fI.gpg-id\fP file for the specified \fIsub-folder\fP (or root if +unspecified) is removed. +.TP +\fBls\fP \fIsubfolder\fP +List names of passwords inside the tree at +.I subfolder +by using the +.BR tree (1) +program. This command is alternatively named \fBlist\fP. +.TP +\fBgrep\fP \fIsearch-string\fP +Searches inside each decrypted password file for \fIsearch-string\fP, and displays line +containing matched string along with filename. Uses +.BR grep (1) +for matching. Make use of the \fIGREP_OPTIONS\fP environment variable to set particular +options. +.TP +\fBfind\fP \fIpass-names\fP... +List names of passwords inside the tree that match \fIpass-names\fP by using the +.BR tree (1) +program. This command is alternatively named \fBsearch\fP. +.TP +\fBshow\fP [ \fI--clip\fP, \fI-c\fP ] \fIpass-name\fP +Decrypt and print a password named \fIpass-name\fP. If \fI--clip\fP or \fI-c\fP +is specified, do not print the password but instead copy the first line to the +clipboard using +.BR xclip (1) +and then restore the clipboard after 45 (or \fIPASSWORD_STORE_CLIP_TIME\fP) seconds. +.TP +\fBinsert\fP [ \fI--echo\fP, \fI-e\fP | \fI--multiline\fP, \fI-m\fP ] [ \fI--force\fP, \fI-f\fP ] \fIpass-name\fP +Insert a new password into the password store called \fIpass-name\fP. This will +read the new password from standard in. If \fI--echo\fP or \fI-e\fP is \fInot\fP specified, +disable keyboard echo when the password is entered and confirm the password by asking +for it twice. If \fI--multiline\fP or \fI-m\fP is specified, lines will be read until +EOF or Ctrl+D is reached. Otherwise, only a single line from standard in is read. Prompt +before overwriting an existing password, unless \fI--force\fP or \fI-f\fP is specified. This +command is alternatively named \fBadd\fP. +.TP +\fBedit\fP \fIpass-name\fP +Insert a new password or edit an existing password using the default text editor specified +by the environment variable \fIEDITOR\fP or using +.BR vi (1) +as a fallback. This mode makes use of temporary files for editing, but care is taken to +ensure that temporary files are created in \fI/dev/shm\fP in order to avoid writing to +difficult-to-erase disk sectors. If \fI/dev/shm\fP is not accessible, fallback to +the ordinary \fITMPDIR\fP location, and print a warning. +.TP +\fBgenerate\fP [ \fI--no-symbols\fP, \fI-n\fP ] [ \fI--clip\fP, \fI-c\fP ] [ \fI--in-place\fP, \fI-i\fP | \fI--force\fP, \fI-f\fP ] \fIpass-name pass-length\fP +Generate a new password using +.BR pwgen (1) +of length \fIpass-length\fP and insert into \fIpass-name\fP. If \fI--no-symbols\fP or \fI-n\fP +is specified, do not use any non-alphanumeric characters in the generated password. +If \fI--clip\fP or \fI-c\fP is specified, do not print the password but instead copy +it to the clipboard using +.BR xclip (1) +and then restore the clipboard after 45 (or \fIPASSWORD_STORE_CLIP_TIME\fP) seconds. +Prompt before overwriting an existing password, +unless \fI--force\fP or \fI-f\fP is specified. If \fI--in-place\fP or \fI-i\fP is +specified, do not interactively prompt, and only replace the first line of the password +file with the new generated password, keeping the remainder of the file intact. +.TP +\fBrm\fP [ \fI--recursive\fP, \fI-r\fP ] [ \fI--force\fP, \fI-f\fP ] \fIpass-name\fP +Remove the password named \fIpass-name\fP from the password store. This command is +alternatively named \fBremove\fP or \fBdelete\fP. If \fI--recursive\fP or \fI-r\fP +is specified, delete pass-name recursively if it is a directory. If \fI--force\fP +or \fI-f\fP is specified, do not interactively prompt before removal. +.TP +\fBmv\fP [ \fI--force\fP, \fI-f\fP ] \fIold-path\fP \fInew-path\fP +Renames the password or directory named \fIold-path\fP to \fInew-path\fP. This +command is alternatively named \fBrename\fP. If \fI--force\fP is specified, +silently overwrite \fInew-path\fP if it exists. If \fInew-path\fP ends in a +trailing \fI/\fP, it is always treated as a directory. Passwords are selectively +reencrypted to the corresponding keys of their new destination. +.TP +\fBcp\fP [ \fI--force\fP, \fI-f\fP ] \fIold-path\fP \fInew-path\fP +Copies the password or directory named \fIold-path\fP to \fInew-path\fP. This +command is alternatively named \fBcopy\fP. If \fI--force\fP is specified, +silently overwrite \fInew-path\fP if it exists. If \fInew-path\fP ends in a +trailing \fI/\fP, it is always treated as a directory. Passwords are selectively +reencrypted to the corresponding keys of their new destination. +.TP +\fBgit\fP \fIgit-command-args\fP... +If the password store is a git repository, pass \fIgit-command-args\fP as arguments to +.BR git (1) +using the password store as the git repository. If \fIgit-command-args\fP is \fBinit\fP, +in addition to initializing the git repository, add the current contents of the password +store to the repository in an initial commit. If the git config key \fIpass.signcommits\fP +is set to \fItrue\fP, then all commits will be signed using \fIuser.signingkey\fP or the +default git signing key. This config key may be turned on using: +.B `pass git config --bool --add pass.signcommits true` +.TP +\fBhelp\fP +Show usage message. +.TP +\fBversion\fP +Show version information. + +.SH SIMPLE EXAMPLES + +.TP +Initialize password store +.B zx2c4@laptop ~ $ pass init Jason@zx2c4.com +.br +mkdir: created directory \[u2018]/home/zx2c4/.password-store\[u2019] +.br +Password store initialized for Jason@zx2c4.com. +.TP +List existing passwords in store +.B zx2c4@laptop ~ $ pass +.br +Password Store +.br +\[u251C]\[u2500]\[u2500] Business +.br +\[u2502] \[u251C]\[u2500]\[u2500] some-silly-business-site.com +.br +\[u2502] \[u2514]\[u2500]\[u2500] another-business-site.net +.br +\[u251C]\[u2500]\[u2500] Email +.br +\[u2502] \[u251C]\[u2500]\[u2500] donenfeld.com +.br +\[u2502] \[u2514]\[u2500]\[u2500] zx2c4.com +.br +\[u2514]\[u2500]\[u2500] France +.br + \[u251C]\[u2500]\[u2500] bank +.br + \[u251C]\[u2500]\[u2500] freebox +.br + \[u2514]\[u2500]\[u2500] mobilephone +.br + +.br +Alternatively, "\fBpass ls\fP". +.TP +Find existing passwords in store that match .com +.B zx2c4@laptop ~ $ pass find .com +.br +Search Terms: .com +.br +\[u251C]\[u2500]\[u2500] Business +.br +\[u2502] \[u251C]\[u2500]\[u2500] some-silly-business-site.com +.br +\[u2514]\[u2500]\[u2500] Email +.br + \[u251C]\[u2500]\[u2500] donenfeld.com +.br + \[u2514]\[u2500]\[u2500] zx2c4.com +.br + +.br +Alternatively, "\fBpass search .com\fP". +.TP +Show existing password +.B zx2c4@laptop ~ $ pass Email/zx2c4.com +.br +sup3rh4x3rizmynam3 +.TP +Copy existing password to clipboard +.B zx2c4@laptop ~ $ pass -c Email/zx2c4.com +.br +Copied Email/jason@zx2c4.com to clipboard. Will clear in 45 seconds. +.TP +Add password to store +.B zx2c4@laptop ~ $ pass insert Business/cheese-whiz-factory +.br +Enter password for Business/cheese-whiz-factory: omg so much cheese what am i gonna do +.TP +Add multiline password to store +.B zx2c4@laptop ~ $ pass insert -m Business/cheese-whiz-factory +.br +Enter contents of Business/cheese-whiz-factory and press Ctrl+D when finished: +.br + +.br +Hey this is my +.br +awesome +.br +multi +.br +line +.br +passworrrrrrrrd. +.br +^D +.TP +Generate new password +.B zx2c4@laptop ~ $ pass generate Email/jasondonenfeld.com 15 +.br +The generated password to Email/jasondonenfeld.com is: +.br +$(-QF&Q=IN2nFBx +.TP +Generate new alphanumeric password +.B zx2c4@laptop ~ $ pass generate -n Email/jasondonenfeld.com 12 +.br +The generated password to Email/jasondonenfeld.com is: +.br +YqFsMkBeO6di +.TP +Generate new password and copy it to the clipboard +.B zx2c4@laptop ~ $ pass generate -c Email/jasondonenfeld.com 19 +.br +Copied Email/jasondonenfeld.com to clipboard. Will clear in 45 seconds. +.TP +Remove password from store +.B zx2c4@laptop ~ $ pass remove Business/cheese-whiz-factory +.br +rm: remove regular file \[u2018]/home/zx2c4/.password-store/Business/cheese-whiz-factory.gpg\[u2019]? y +.br +removed \[u2018]/home/zx2c4/.password-store/Business/cheese-whiz-factory.gpg\[u2019] + +.SH EXTENDED GIT EXAMPLE +Here, we initialize new password store, create a git repository, and then manipulate and sync passwords. Make note of the arguments to the first call of \fBpass git push\fP; consult +.BR git-push (1) +for more information. + +.B zx2c4@laptop ~ $ pass init Jason@zx2c4.com +.br +mkdir: created directory \[u2018]/home/zx2c4/.password-store\[u2019] +.br +Password store initialized for Jason@zx2c4.com. + +.B zx2c4@laptop ~ $ pass git init +.br +Initialized empty Git repository in /home/zx2c4/.password-store/.git/ +.br +[master (root-commit) 998c8fd] Added current contents of password store. +.br + 1 file changed, 1 insertion(+) +.br + create mode 100644 .gpg-id + +.B zx2c4@laptop ~ $ pass git remote add origin kexec.com:pass-store + +.B zx2c4@laptop ~ $ pass generate Amazon/amazonemail@email.com 21 +.br +mkdir: created directory \[u2018]/home/zx2c4/.password-store/Amazon\[u2019] +.br +[master 30fdc1e] Added generated password for Amazon/amazonemail@email.com to store. +.br +1 file changed, 0 insertions(+), 0 deletions(-) +.br +create mode 100644 Amazon/amazonemail@email.com.gpg +.br +The generated password to Amazon/amazonemail@email.com is: +.br +<5m,_BrZY`antNDxKN<0A + +.B zx2c4@laptop ~ $ pass git push -u --all +.br +Counting objects: 4, done. +.br +Delta compression using up to 2 threads. +.br +Compressing objects: 100% (3/3), done. +.br +Writing objects: 100% (4/4), 921 bytes, done. +.br +Total 4 (delta 0), reused 0 (delta 0) +.br +To kexec.com:pass-store +.br +* [new branch] master -> master +.br +Branch master set up to track remote branch master from origin. + +.B zx2c4@laptop ~ $ pass insert Amazon/otheraccount@email.com +.br +Enter password for Amazon/otheraccount@email.com: som3r3a11yb1gp4ssw0rd!!88** +.br +[master b9b6746] Added given password for Amazon/otheraccount@email.com to store. +.br +1 file changed, 0 insertions(+), 0 deletions(-) +.br +create mode 100644 Amazon/otheraccount@email.com.gpg + +.B zx2c4@laptop ~ $ pass rm Amazon/amazonemail@email.com +.br +rm: remove regular file \[u2018]/home/zx2c4/.password-store/Amazon/amazonemail@email.com.gpg\[u2019]? y +.br +removed \[u2018]/home/zx2c4/.password-store/Amazon/amazonemail@email.com.gpg\[u2019] +.br +rm 'Amazon/amazonemail@email.com.gpg' +.br +[master 288b379] Removed Amazon/amazonemail@email.com from store. +.br +1 file changed, 0 insertions(+), 0 deletions(-) +.br +delete mode 100644 Amazon/amazonemail@email.com.gpg + +.B zx2c4@laptop ~ $ pass git push +.br +Counting objects: 9, done. +.br +Delta compression using up to 2 threads. +.br +Compressing objects: 100% (5/5), done. +.br +Writing objects: 100% (7/7), 1.25 KiB, done. +.br +Total 7 (delta 0), reused 0 (delta 0) +.br +To kexec.com:pass-store + +.SH FILES + +.TP +.B ~/.password-store +The default password storage directory. +.TP +.B ~/.password-store/.gpg-id +Contains the default gpg key identification used for encryption and decryption. +Multiple gpg keys may be specified in this file, one per line. If this file +exists in any sub directories, passwords inside those sub directories are +encrypted using those keys. This should be set using the \fBinit\fP command. + +.SH ENVIRONMENT VARIABLES + +.TP +.I PASSWORD_STORE_DIR +Overrides the default password storage directory. +.TP +.I PASSWORD_STORE_KEY +Overrides the default gpg key identification set by \fBinit\fP. Keys must not +contain spaces and thus use of the hexidecimal key signature is recommended. +Multiple keys may be specified separated by spaces. +.TP +.I PASSWORD_STORE_GIT +Overrides the default root of the git repository, which is helpful if +\fIPASSWORD_STORE_DIR\fP is temporarily set to a sub-directory of the default +password store. +.TP +.I PASSWORD_STORE_GPG_OPTS +Additional options to be passed to all invocations of GPG. +.TP +.I PASSWORD_STORE_X_SELECTION +Overrides the selection passed to \fBxclip\fP, by default \fIclipboard\fP. See +.BR xclip (1) +for more info. +.TP +.I PASSWORD_STORE_CLIP_TIME +Specifies the number of seconds to wait before restoring the clipboard, by default +\fI45\fP seconds. +.TP +.I PASSWORD_STORE_UMASK +Sets the umask of all files modified by pass, by default \fI077\fP. +.TP +.I EDITOR +The location of the text editor used by \fBedit\fP. +.SH SEE ALSO +.BR gpg2 (1), +.BR pwgen (1), +.BR git (1), +.BR xclip (1). + +.SH AUTHOR +.B pass +was written by +.MT Jason@zx2c4.com +Jason A. Donenfeld +.ME . +For updates and more information, a project page is available on the +.UR http://\:www.passwordstore.org/ +World Wide Web +.UE . + +.SH COPYING +This program is free software; you can redistribute it and/or +modify it under the terms of the GNU General Public License +as published by the Free Software Foundation; either version 2 +of the License, or (at your option) any later version. + +This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU General Public License for more details. + +You should have received a copy of the GNU General Public License +along with this program; if not, write to the Free Software +Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.