pass.1 (17863B)
1 .TH PASS 1 "2014 March 18" ZX2C4 "Password Store" 2 3 .SH NAME 4 pass - stores, retrieves, generates, and synchronizes passwords securely 5 6 .SH SYNOPSIS 7 .B pass 8 [ 9 .I COMMAND 10 ] [ 11 .I OPTIONS 12 ]... [ 13 .I ARGS 14 ]... 15 16 .SH DESCRIPTION 17 18 .B pass 19 is a very simple password store that keeps passwords inside 20 .BR gpg2 (1) 21 encrypted files inside a simple directory tree residing at 22 .IR ~/.password-store . 23 The 24 .B pass 25 utility provides a series of commands for manipulating the password store, 26 allowing the user to add, remove, edit, synchronize, generate, and manipulate 27 passwords. 28 29 If no COMMAND is specified, COMMAND defaults to either 30 .B show 31 or 32 .BR ls , 33 depending on the type of specifier in ARGS. Alternatively, if \fIPASSWORD_STORE_ENABLE_EXTENSIONS\fP 34 is set to "true", and the file \fI.extensions/COMMAND.bash\fP exists inside the 35 password store and is executable, then it is sourced into the environment, 36 passing any arguments and environment variables. Extensions existing in a 37 system-wide directory, only installable by the administrator, are always enabled. 38 39 Otherwise COMMAND must be one of the valid commands listed below. 40 41 Several of the commands below rely on or provide additional functionality if 42 the password store directory is also a git repository. If the password store 43 directory is a git repository, all password store modification commands will 44 cause a corresponding git commit. Sub-directories may be separate nested git 45 repositories, and pass will use the inner-most directory relative to the 46 current password. See the \fIEXTENDED GIT EXAMPLE\fP section for a detailed 47 description using \fBinit\fP and 48 .BR git (1). 49 50 The \fBinit\fP command must be run before other commands in order to initialize 51 the password store with the correct gpg key id. Passwords are encrypted using 52 the gpg key set with \fBinit\fP. 53 54 There is a corresponding bash completion script for use with tab completing 55 password names in 56 .BR bash (1). 57 58 .SH COMMANDS 59 60 .TP 61 \fBinit\fP [ \fI--path=sub-folder\fP, \fI-p sub-folder\fP ] \fIgpg-id...\fP 62 Initialize new password storage and use 63 .I gpg-id 64 for encryption. Multiple gpg-ids may be specified, in order to encrypt each 65 password with multiple ids. This command must be run first before a password 66 store can be used. If the specified \fIgpg-id\fP is different from the key 67 used in any existing files, these files will be reencrypted to use the new id. 68 Note that use of 69 .BR gpg-agent (1) 70 is recommended so that the batch decryption does not require as much user 71 intervention. If \fI--path\fP or \fI-p\fP is specified, along with an argument, 72 a specific gpg-id or set of gpg-ids is assigned for that specific sub folder of 73 the password store. If only one \fIgpg-id\fP is given, and it is an empty string, 74 then the current \fI.gpg-id\fP file for the specified \fIsub-folder\fP (or root if 75 unspecified) is removed. 76 .TP 77 \fBls\fP \fIsubfolder\fP 78 List names of passwords inside the tree at 79 .I subfolder 80 by using the 81 .BR tree (1) 82 program. This command is alternatively named \fBlist\fP. 83 .TP 84 \fBgrep\fP [\fIGREPOPTIONS\fP] \fIsearch-string\fP 85 Searches inside each decrypted password file for \fIsearch-string\fP, and displays line 86 containing matched string along with filename. Uses 87 .BR grep (1) 88 for matching. \fIGREPOPTIONS\fP are passed to 89 .BR grep (1) 90 as-is. (Note: the \fIGREP_OPTIONS\fP environment variable functions as well.) 91 .TP 92 \fBfind\fP \fIpass-names\fP... 93 List names of passwords inside the tree that match \fIpass-names\fP by using the 94 .BR tree (1) 95 program. This command is alternatively named \fBsearch\fP. 96 .TP 97 \fBshow\fP [ \fI--clip\fP[=\fIline-number\fP], \fI-c\fP[\fIline-number\fP] ] [ \fI--qrcode\fP[=\fIline-number\fP], \fI-q\fP[\fIline-number\fP] ] \fIpass-name\fP 98 Decrypt and print a password named \fIpass-name\fP. If \fI--clip\fP or \fI-c\fP 99 is specified, do not print the password but instead copy the first (or otherwise specified) 100 line to the clipboard using 101 .BR xclip (1) 102 or 103 .BR wl-clipboard(1) 104 and then restore the clipboard after 45 (or \fIPASSWORD_STORE_CLIP_TIME\fP) seconds. If \fI--qrcode\fP 105 or \fI-q\fP is specified, do not print the password but instead display a QR code using 106 .BR qrencode (1) 107 either to the terminal or graphically if supported. 108 .TP 109 \fBinsert\fP [ \fI--echo\fP, \fI-e\fP | \fI--multiline\fP, \fI-m\fP ] [ \fI--force\fP, \fI-f\fP ] \fIpass-name\fP 110 Insert a new password into the password store called \fIpass-name\fP. This will 111 read the new password from standard in. If \fI--echo\fP or \fI-e\fP is \fInot\fP specified, 112 disable keyboard echo when the password is entered and confirm the password by asking 113 for it twice. If \fI--multiline\fP or \fI-m\fP is specified, lines will be read until 114 EOF or Ctrl+D is reached. Otherwise, only a single line from standard in is read. Prompt 115 before overwriting an existing password, unless \fI--force\fP or \fI-f\fP is specified. This 116 command is alternatively named \fBadd\fP. 117 .TP 118 \fBedit\fP \fIpass-name\fP 119 Insert a new password or edit an existing password using the default text editor specified 120 by the environment variable \fIEDITOR\fP or using 121 .BR vi (1) 122 as a fallback. This mode makes use of temporary files for editing, but care is taken to 123 ensure that temporary files are created in \fI/dev/shm\fP in order to avoid writing to 124 difficult-to-erase disk sectors. If \fI/dev/shm\fP is not accessible, fallback to 125 the ordinary \fITMPDIR\fP location, and print a warning. 126 .TP 127 \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 128 Generate a new password using \fB/dev/urandom\fP of length \fIpass-length\fP 129 (or \fIPASSWORD_STORE_GENERATED_LENGTH\fP if unspecified) and insert into 130 \fIpass-name\fP. If \fI--no-symbols\fP or \fI-n\fP is specified, do not use 131 any non-alphanumeric characters in the generated password. The character sets used 132 in generating passwords can be changed with the \fIPASSWORD_STORE_CHARACTER_SET\fP and 133 \fIPASSWORD_STORE_CHARACTER_SET_NO_SYMBOLS\fP environment variables, described below. 134 If \fI--clip\fP or \fI-c\fP is specified, do not print the password but instead copy 135 it to the clipboard using 136 .BR xclip (1) 137 or 138 .BR wl-clipboard(1) 139 and then restore the clipboard after 45 (or \fIPASSWORD_STORE_CLIP_TIME\fP) seconds. If \fI--qrcode\fP 140 or \fI-q\fP is specified, do not print the password but instead display a QR code using 141 .BR qrencode (1) 142 either to the terminal or graphically if supported. Prompt before overwriting an existing password, 143 unless \fI--force\fP or \fI-f\fP is specified. If \fI--in-place\fP or \fI-i\fP is 144 specified, do not interactively prompt, and only replace the first line of the password 145 file with the new generated password, keeping the remainder of the file intact. 146 .TP 147 \fBrm\fP [ \fI--recursive\fP, \fI-r\fP ] [ \fI--force\fP, \fI-f\fP ] \fIpass-name\fP 148 Remove the password named \fIpass-name\fP from the password store. This command is 149 alternatively named \fBremove\fP or \fBdelete\fP. If \fI--recursive\fP or \fI-r\fP 150 is specified, delete pass-name recursively if it is a directory. If \fI--force\fP 151 or \fI-f\fP is specified, do not interactively prompt before removal. 152 .TP 153 \fBmv\fP [ \fI--force\fP, \fI-f\fP ] \fIold-path\fP \fInew-path\fP 154 Renames the password or directory named \fIold-path\fP to \fInew-path\fP. This 155 command is alternatively named \fBrename\fP. If \fI--force\fP is specified, 156 silently overwrite \fInew-path\fP if it exists. If \fInew-path\fP ends in a 157 trailing \fI/\fP, it is always treated as a directory. Passwords are selectively 158 reencrypted to the corresponding keys of their new destination. 159 .TP 160 \fBcp\fP [ \fI--force\fP, \fI-f\fP ] \fIold-path\fP \fInew-path\fP 161 Copies the password or directory named \fIold-path\fP to \fInew-path\fP. This 162 command is alternatively named \fBcopy\fP. If \fI--force\fP is specified, 163 silently overwrite \fInew-path\fP if it exists. If \fInew-path\fP ends in a 164 trailing \fI/\fP, it is always treated as a directory. Passwords are selectively 165 reencrypted to the corresponding keys of their new destination. 166 .TP 167 \fBgit\fP \fIgit-command-args\fP... 168 If the password store is a git repository, pass \fIgit-command-args\fP as arguments to 169 .BR git (1) 170 using the password store as the git repository. If \fIgit-command-args\fP is \fBinit\fP, 171 in addition to initializing the git repository, add the current contents of the password 172 store to the repository in an initial commit. If the git config key \fIpass.signcommits\fP 173 is set to \fItrue\fP, then all commits will be signed using \fIuser.signingkey\fP or the 174 default git signing key. This config key may be turned on using: 175 .B `pass git config --bool --add pass.signcommits true` 176 .TP 177 \fBhelp\fP 178 Show usage message. 179 .TP 180 \fBversion\fP 181 Show version information. 182 183 .SH SIMPLE EXAMPLES 184 185 .TP 186 Initialize password store 187 .B zx2c4@laptop ~ $ pass init Jason@zx2c4.com 188 .br 189 mkdir: created directory \[u2018]/home/zx2c4/.password-store\[u2019] 190 .br 191 Password store initialized for Jason@zx2c4.com. 192 .TP 193 List existing passwords in store 194 .B zx2c4@laptop ~ $ pass 195 .br 196 Password Store 197 .br 198 \[u251C]\[u2500]\[u2500] Business 199 .br 200 \[u2502] \[u251C]\[u2500]\[u2500] some-silly-business-site.com 201 .br 202 \[u2502] \[u2514]\[u2500]\[u2500] another-business-site.net 203 .br 204 \[u251C]\[u2500]\[u2500] Email 205 .br 206 \[u2502] \[u251C]\[u2500]\[u2500] donenfeld.com 207 .br 208 \[u2502] \[u2514]\[u2500]\[u2500] zx2c4.com 209 .br 210 \[u2514]\[u2500]\[u2500] France 211 .br 212 \[u251C]\[u2500]\[u2500] bank 213 .br 214 \[u251C]\[u2500]\[u2500] freebox 215 .br 216 \[u2514]\[u2500]\[u2500] mobilephone 217 .br 218 219 .br 220 Alternatively, "\fBpass ls\fP". 221 .TP 222 Find existing passwords in store that match .com 223 .B zx2c4@laptop ~ $ pass find .com 224 .br 225 Search Terms: .com 226 .br 227 \[u251C]\[u2500]\[u2500] Business 228 .br 229 \[u2502] \[u251C]\[u2500]\[u2500] some-silly-business-site.com 230 .br 231 \[u2514]\[u2500]\[u2500] Email 232 .br 233 \[u251C]\[u2500]\[u2500] donenfeld.com 234 .br 235 \[u2514]\[u2500]\[u2500] zx2c4.com 236 .br 237 238 .br 239 Alternatively, "\fBpass search .com\fP". 240 .TP 241 Show existing password 242 .B zx2c4@laptop ~ $ pass Email/zx2c4.com 243 .br 244 sup3rh4x3rizmynam3 245 .TP 246 Copy existing password to clipboard 247 .B zx2c4@laptop ~ $ pass -c Email/zx2c4.com 248 .br 249 Copied Email/jason@zx2c4.com to clipboard. Will clear in 45 seconds. 250 .TP 251 Add password to store 252 .B zx2c4@laptop ~ $ pass insert Business/cheese-whiz-factory 253 .br 254 Enter password for Business/cheese-whiz-factory: omg so much cheese what am i gonna do 255 .TP 256 Add multiline password to store 257 .B zx2c4@laptop ~ $ pass insert -m Business/cheese-whiz-factory 258 .br 259 Enter contents of Business/cheese-whiz-factory and press Ctrl+D when finished: 260 .br 261 262 .br 263 Hey this is my 264 .br 265 awesome 266 .br 267 multi 268 .br 269 line 270 .br 271 passworrrrrrrrd. 272 .br 273 ^D 274 .TP 275 Generate new password 276 .B zx2c4@laptop ~ $ pass generate Email/jasondonenfeld.com 15 277 .br 278 The generated password to Email/jasondonenfeld.com is: 279 .br 280 $(-QF&Q=IN2nFBx 281 .TP 282 Generate new alphanumeric password 283 .B zx2c4@laptop ~ $ pass generate -n Email/jasondonenfeld.com 12 284 .br 285 The generated password to Email/jasondonenfeld.com is: 286 .br 287 YqFsMkBeO6di 288 .TP 289 Generate new password and copy it to the clipboard 290 .B zx2c4@laptop ~ $ pass generate -c Email/jasondonenfeld.com 19 291 .br 292 Copied Email/jasondonenfeld.com to clipboard. Will clear in 45 seconds. 293 .TP 294 Remove password from store 295 .B zx2c4@laptop ~ $ pass remove Business/cheese-whiz-factory 296 .br 297 rm: remove regular file \[u2018]/home/zx2c4/.password-store/Business/cheese-whiz-factory.gpg\[u2019]? y 298 .br 299 removed \[u2018]/home/zx2c4/.password-store/Business/cheese-whiz-factory.gpg\[u2019] 300 301 .SH EXTENDED GIT EXAMPLE 302 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 303 .BR git-push (1) 304 for more information. 305 306 .B zx2c4@laptop ~ $ pass init Jason@zx2c4.com 307 .br 308 mkdir: created directory \[u2018]/home/zx2c4/.password-store\[u2019] 309 .br 310 Password store initialized for Jason@zx2c4.com. 311 312 .B zx2c4@laptop ~ $ pass git init 313 .br 314 Initialized empty Git repository in /home/zx2c4/.password-store/.git/ 315 .br 316 [master (root-commit) 998c8fd] Added current contents of password store. 317 .br 318 1 file changed, 1 insertion(+) 319 .br 320 create mode 100644 .gpg-id 321 322 .B zx2c4@laptop ~ $ pass git remote add origin kexec.com:pass-store 323 324 .B zx2c4@laptop ~ $ pass generate Amazon/amazonemail@email.com 21 325 .br 326 mkdir: created directory \[u2018]/home/zx2c4/.password-store/Amazon\[u2019] 327 .br 328 [master 30fdc1e] Added generated password for Amazon/amazonemail@email.com to store. 329 .br 330 1 file changed, 0 insertions(+), 0 deletions(-) 331 .br 332 create mode 100644 Amazon/amazonemail@email.com.gpg 333 .br 334 The generated password to Amazon/amazonemail@email.com is: 335 .br 336 <5m,_BrZY`antNDxKN<0A 337 338 .B zx2c4@laptop ~ $ pass git push -u --all 339 .br 340 Counting objects: 4, done. 341 .br 342 Delta compression using up to 2 threads. 343 .br 344 Compressing objects: 100% (3/3), done. 345 .br 346 Writing objects: 100% (4/4), 921 bytes, done. 347 .br 348 Total 4 (delta 0), reused 0 (delta 0) 349 .br 350 To kexec.com:pass-store 351 .br 352 * [new branch] master -> master 353 .br 354 Branch master set up to track remote branch master from origin. 355 356 .B zx2c4@laptop ~ $ pass insert Amazon/otheraccount@email.com 357 .br 358 Enter password for Amazon/otheraccount@email.com: som3r3a11yb1gp4ssw0rd!!88** 359 .br 360 [master b9b6746] Added given password for Amazon/otheraccount@email.com to store. 361 .br 362 1 file changed, 0 insertions(+), 0 deletions(-) 363 .br 364 create mode 100644 Amazon/otheraccount@email.com.gpg 365 366 .B zx2c4@laptop ~ $ pass rm Amazon/amazonemail@email.com 367 .br 368 rm: remove regular file \[u2018]/home/zx2c4/.password-store/Amazon/amazonemail@email.com.gpg\[u2019]? y 369 .br 370 removed \[u2018]/home/zx2c4/.password-store/Amazon/amazonemail@email.com.gpg\[u2019] 371 .br 372 rm 'Amazon/amazonemail@email.com.gpg' 373 .br 374 [master 288b379] Removed Amazon/amazonemail@email.com from store. 375 .br 376 1 file changed, 0 insertions(+), 0 deletions(-) 377 .br 378 delete mode 100644 Amazon/amazonemail@email.com.gpg 379 380 .B zx2c4@laptop ~ $ pass git push 381 .br 382 Counting objects: 9, done. 383 .br 384 Delta compression using up to 2 threads. 385 .br 386 Compressing objects: 100% (5/5), done. 387 .br 388 Writing objects: 100% (7/7), 1.25 KiB, done. 389 .br 390 Total 7 (delta 0), reused 0 (delta 0) 391 .br 392 To kexec.com:pass-store 393 394 .SH FILES 395 396 .TP 397 .B ~/.password-store 398 The default password storage directory. 399 .TP 400 .B ~/.password-store/.gpg-id 401 Contains the default gpg key identification used for encryption and decryption. 402 Multiple gpg keys may be specified in this file, one per line. If this file 403 exists in any sub directories, passwords inside those sub directories are 404 encrypted using those keys. This should be set using the \fBinit\fP command. 405 .TP 406 .B ~/.password-store/.extensions 407 The directory containing extension files. 408 409 .SH ENVIRONMENT VARIABLES 410 411 .TP 412 .I PASSWORD_STORE_DIR 413 Overrides the default password storage directory. 414 .TP 415 .I PASSWORD_STORE_KEY 416 Overrides the default gpg key identification set by \fBinit\fP. Keys must not 417 contain spaces and thus use of the hexadecimal key signature is recommended. 418 Multiple keys may be specified separated by spaces. 419 .TP 420 .I PASSWORD_STORE_GPG_OPTS 421 Additional options to be passed to all invocations of GPG. 422 .TP 423 .I PASSWORD_STORE_X_SELECTION 424 Overrides the selection passed to \fBxclip\fP, by default \fIclipboard\fP. See 425 .BR xclip (1) 426 for more info. 427 .TP 428 .I PASSWORD_STORE_CLIP_TIME 429 Specifies the number of seconds to wait before restoring the clipboard, by default 430 \fI45\fP seconds. 431 .TP 432 .I PASSWORD_STORE_UMASK 433 Sets the umask of all files modified by pass, by default \fI077\fP. 434 .TP 435 .I PASSWORD_STORE_GENERATED_LENGTH 436 The default password length if the \fIpass-length\fP parameter to \fBgenerate\fP 437 is unspecified. 438 .TP 439 .I PASSWORD_STORE_CHARACTER_SET 440 The character set to be used in password generation for \fBgenerate\fP. This value 441 is to be interpreted by \fBtr\fP. See 442 .BR tr (1) 443 for more info. 444 .TP 445 .I PASSWORD_STORE_CHARACTER_SET_NO_SYMBOLS 446 The character set to be used in no-symbol password generation for \fBgenerate\fP, 447 when \fI--no-symbols\fP, \fI-n\fP is specified. This value is to be interpreted 448 by \fBtr\fP. See 449 .BR tr (1) 450 for more info. 451 .TP 452 .I PASSWORD_STORE_ENABLE_EXTENSIONS 453 This environment variable must be set to "true" for extensions to be enabled. 454 .TP 455 .I PASSWORD_STORE_EXTENSIONS_DIR 456 The location to look for executable extension files, by default 457 \fIPASSWORD_STORE_DIR/.extensions\fP. 458 .TP 459 .I PASSWORD_STORE_SIGNING_KEY 460 If this environment variable is set, then all \fB.gpg-id\fP files and non-system extension files 461 must be signed using a detached signature using the GPG key specified by the full 40 character 462 upper-case fingerprint in this variable. If multiple fingerprints are specified, each 463 separated by a whitespace character, then signatures must match at least one. 464 The \fBinit\fP command will keep signatures of \fB.gpg-id\fP files up to date. 465 .TP 466 .I EDITOR 467 The location of the text editor used by \fBedit\fP. 468 .SH SEE ALSO 469 .BR gpg2 (1), 470 .BR tr (1), 471 .BR git (1), 472 .BR xclip (1), 473 .BR wl-clipboard (1), 474 .BR qrencode (1). 475 476 .SH AUTHOR 477 .B pass 478 was written by 479 .MT Jason@zx2c4.com 480 Jason A. Donenfeld 481 .ME . 482 For updates and more information, a project page is available on the 483 .UR http://\:www.passwordstore.org/ 484 World Wide Web 485 .UE . 486 487 .SH COPYING 488 This program is free software; you can redistribute it and/or 489 modify it under the terms of the GNU General Public License 490 as published by the Free Software Foundation; either version 2 491 of the License, or (at your option) any later version. 492 493 This program is distributed in the hope that it will be useful, 494 but WITHOUT ANY WARRANTY; without even the implied warranty of 495 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 496 GNU General Public License for more details. 497 498 You should have received a copy of the GNU General Public License 499 along with this program; if not, write to the Free Software 500 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.