jmarya/knowledge
jmarya/knowledge
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

add pass

Browse source
This commit is contained in:
JMARyA 2024-09-10 10:22:22 +02:00
parent 4f26dd7c99
commit b1a1330d80
Signed by: jmarya
GPG key ID: 901B2ADDF27C2263
2 changed files with 252 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
technology/applications/Applications.md
View file

@ -227,6 +227,7 @@ rev: 2024-07-14
- [OpenSSL](../cryptography/OpenSSL.md)
- [tomb](./cli/tomb.md)
- [dysk](./cli/dysk.md)
- [pass](./cli/pass.md)
## System
- [Core Utils](./cli/system/Core%20Utils.md)

251
technology/applications/cli/pass.md Normal file
View file

@ -0,0 +1,251 @@
---
obj: application
website: https://www.passwordstore.org
repo: https://git.zx2c4.com/password-store
---
# Passwordstore
pass is a very simple password store that keeps passwords inside [GPG](../../cryptography/GPG.md) encrypted files inside a simple directory tree residing at `~/.password-store`. The pass utility provides a series of commands for manipulating the password store, allowing the user to add, remove, edit, synchronize, generate, and manipulate passwords.
## Usage
Usage: `pass [ COMMAND ] [ OPTIONS ]... [ ARGS ]...`
If no `COMMAND` is specified, `COMMAND` defaults to either `show` or `ls`, depending on the type of specifier in `ARGS`. Alternatively, if `$PASSWORD_STORE_ENABLE_EXTENSIONS` is set to "true", and the file `.extensions/COMMAND.bash` exists inside the password store and is executable, then it is sourced into the environment, passing any arguments and environment variables. Extensions existing in a system-wide directory, only installable by the administrator, are always enabled.
Several of the commands below rely on or provide additional functionality if the password store directory is also a [git](../../dev/Git.md) repository. If the password store directory is a git repository, all password store modification commands will cause a corresponding git commit. Sub-directories may be separate nested git repositories, and pass will use the inner-most directory relative to the current password.
The `init` command must be run before other commands in order to initialize the password store with the correct [GPG](../../cryptography/GPG.md) key id. Passwords are encrypted using the [GPG](../../cryptography/GPG.md) key set with `init`.
### Commands
- `init [ --path=sub-folder, -p sub-folder ] gpg-id...`
Initialize new password storage and use `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 `gpg-id` is different from the key used in any existing files, these files will be reencrypted to use the new id. Note that use of gpg-agent is recommended so that the batch decryption does not require as much user intervention. If `--path` or `-p` 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 `gpg-id` is given, and it is an empty string, then the current `.gpg-id` file for the specified sub-folder (or root if unspecified) is removed.
- `ls subfolder`
List names of passwords inside the tree at subfolder by using the `tree` program. This command is alternatively named `list`.
- `grep [GREPOPTIONS] search-string`
Searches inside each decrypted password file for search-string, and displays line containing matched string along with filename. Uses `grep` for matching. `GREPOPTIONS` are passed to `grep` as-is. (Note: the `$GREP_OPTIONS` environment variable functions as well.)
- `find pass-names...`
List names of passwords inside the tree that match pass-names by using the `tree` program. This command is alternatively named `search`.
- `show [ --clip[=line-number], -c[line-number] ] [--qrcode[=line-number], -q[line-number] ] pass-name`
Decrypt and print a password named `pass-name`. If `--clip` or `-c` is specified, do not print the password but instead copy the first (or otherwise specified) line to the clipboard using `xclip` or `wl-clipboard` and then restore the clipboard after 45 (or `$PASSWORD_STORE_CLIP_TIME`) seconds. If `--qrcode` or `-q` is specified, do not print the password but instead display a QR code using `qrencode` either to the terminal or graphically if supported.
- `insert [ --echo, -e | --multiline, -m ] [ --force, -f ] pass-name`
Insert a new password into the password store called `pass-name`. This will read the new password from standard in. If `--echo` or `-e` is not specified, disable keyboard echo when the password is entered and confirm the password by asking for it twice. If `--multiline` or `-m` 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 `--force` or `-f` is specified. This command is alternatively named `add`.
- `edit pass-name`
Insert a new password or edit an existing password using the default text editor specified by the environment variable `$EDITOR` or using `vi` as a fallback. This mode makes use of temporary files for editing, but care is taken to ensure that temporary files are created in `/dev/shm` in order to avoid writing to difficult-to-erase disk sectors. If `/dev/shm` is not accessible, fallback to the ordinary `TMPDIR` location, and print a warning.
- `generate [ --no-symbols, -n ] [ --clip, -c ] [ --in-place, -i | --force, -f ] pass-name [pass-length]`
Generate a new password using `/dev/urandom` of length `pass-length` (or `$PASSWORD_STORE_GENERATED_LENGTH` if unspecified) and insert into `pass-name`. If `--no-symbols` or `-n` is specified, do not use any non-alphanumeric characters in the generated password. The character sets used in generating passwords can be changed with the `$PASSWORD_STORE_CHARACTER_SET` and `$PASSWORD_STORE_CHARACTER_SET_NO_SYMBOLS` environment variables, described below. If `--clip` or `-c` is specified, do not print the password but instead copy it to the clipboard using `xclip` or `wl-clipboard` and then restore the clipboard after 45 (or `$PASSWORD_STORE_CLIP_TIME`) seconds. If `--qrcode` or `-q` is specified, do not print the password but instead display a QR code using `qrencode` either to the terminal or graphically if supported. Prompt before overwriting an existing password, unless `--force` or `-f` is specified. If `--in-place` or `-i` 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.
- `rm [ --recursive, -r ] [ --force, -f ] pass-name`
Remove the password named `pass-name` from the password store. This command is alternatively named `remove` or `delete`. If `--recursive` or `-r` is specified, delete `pass-name` recursively if it is a directory. If `--force` or `-f` is specified, do not interactively prompt before removal.
- `mv [ --force, -f ] old-path new-path`
Renames the password or directory named `old-path` to `new-path`. This command is alternatively named `rename`. If `--force` is specified, silently overwrite `new-path` if it exists. If `new-path` ends in a trailing `/`, it is always treated as a directory. Passwords are selectively reencrypted to the corresponding keys of their new destination.
- `cp [ --force, -f ] old-path new-path`
Copies the password or directory named `old-path` to `new-path`. This command is alternatively named `copy`. If `--force` is specified, silently overwrite `new-path` if it exists. If `new-path` ends in a trailing `/`, it is always treated as a directory. Passwords are selectively reencrypted to the corresponding keys of their new destination.
- `git git-command-args...`
If the password store is a [git](../../dev/Git.md) repository, pass `git-command-args` as arguments to [git](../../dev/Git.md) using the password store as the git repository. If `git-command-args` is `init`, 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 `pass.signcommits` is set to true, then all commits will be signed using `user.signingkey` or the default git signing key. This config key may be turned on using: `pass git config --bool --add pass.signcommits true`
### Examples
#### Initialize password store
```shell
zx2c4@laptop ˜ $ pass init Jason@zx2c4.com
mkdir: created directory ‘/home/zx2c4/.password-store’
Password store initialized for Jason@zx2c4.com.
```
#### List existing passwords in store
```shell
zx2c4@laptop ˜ $ pass
Password Store
├── Business
│ ├── some-silly-business-site.com
│ └── another-business-site.net
├── Email
│ ├── donenfeld.com
│ └── zx2c4.com
└── France
├── bank
├── freebox
└── mobilephone
```
Alternatively: `pass ls`
#### Find existing passwords in store that match .com
```shell
zx2c4@laptop ˜ $ pass find .com
Search Terms: .com
├── Business
│ ├── some-silly-business-site.com
└── Email
├── donenfeld.com
└── zx2c4.com
```
Alternatively: `pass search .com`
#### Show existing password
```shell
zx2c4@laptop ˜ $ pass Email/zx2c4.com
sup3rh4x3rizmynam3
```
#### Copy existing password to clipboard
```shell
zx2c4@laptop ˜ $ pass -c Email/zx2c4.com
Copied Email/jason@zx2c4.com to clipboard. Will clear in 45 seconds.
```
#### Add password to store
```shell
zx2c4@laptop ˜ $ pass insert Business/cheese-whiz-factory
Enter password for Business/cheese-whiz-factory: omg so much cheese what am i gonna do
```
#### Add multiline password to store
```shell
zx2c4@laptop ˜ $ pass insert -m Business/cheese-whiz-factory
Enter contents of Business/cheese-whiz-factory and press Ctrl+D when finished:
Hey this is my
awesome
multi
line
passworrrrrrrrd.
^D
```
#### Generate new password
```shell
zx2c4@laptop ˜ $ pass generate Email/jasondonenfeld.com 15
The generated password to Email/jasondonenfeld.com is:
$(-QF&Q=IN2nFBx
```
#### Remove password from store
```shell
zx2c4@laptop ˜ $ pass remove Business/cheese-whiz-factory
rm: remove regular file ‘/home/zx2c4/.password-store/Business/cheese-whiz-factory.gpg’? y
removed ‘/home/zx2c4/.password-store/Business/cheese-whiz-factory.gpg’
```
### Git Examples
Here, we initialize new password store, create a [git](../../dev/Git.md) repository, and then manipulate and sync passwords.
```shell
zx2c4@laptop ˜ $ pass init Jason@zx2c4.com
mkdir: created directory ‘/home/zx2c4/.password-store’
Password store initialized for Jason@zx2c4.com.
zx2c4@laptop ˜ $ pass git init
Initialized empty Git repository in /home/zx2c4/.password-store/.git/
[master (root-commit) 998c8fd] Added current contents of password store.
1 file changed, 1 insertion(+)
create mode 100644 .gpg-id
zx2c4@laptop ˜ $ pass git remote add origin kexec.com:pass-store
zx2c4@laptop ˜ $ pass generate Amazon/amazonemail@email.com 21
mkdir: created directory ‘/home/zx2c4/.password-store/Amazon’
[master 30fdc1e] Added generated password for Amazon/amazonemail@email.com to store.
1 file changed, 0 insertions(+), 0 deletions(-)
create mode 100644 Amazon/amazonemail@email.com.gpg
The generated password to Amazon/amazonemail@email.com is:
<5m,_BrZY‘antNDxKN<0A
zx2c4@laptop ˜ $ pass git push -u --all
Counting objects: 4, done.
Delta compression using up to 2 threads.
Compressing objects: 100% (3/3), done.
Writing objects: 100% (4/4), 921 bytes, done.
Total 4 (delta 0), reused 0 (delta 0)
To kexec.com:pass-store
* [new branch] master -> master
Branch master set up to track remote branch master from origin.
zx2c4@laptop ˜ $ pass insert Amazon/otheraccount@email.com
Enter password for Amazon/otheraccount@email.com: som3r3a11yb1gp4ssw0rd!!88**
[master b9b6746] Added given password for Amazon/otheraccount@email.com to store.
1 file changed, 0 insertions(+), 0 deletions(-)
create mode 100644 Amazon/otheraccount@email.com.gpg
zx2c4@laptop ˜ $ pass rm Amazon/amazonemail@email.com
rm: remove regular file ‘/home/zx2c4/.password-store/Amazon/amazonemail@email.com.gpg’? y
removed ‘/home/zx2c4/.password-store/Amazon/amazonemail@email.com.gpg’
rm ’Amazon/amazonemail@email.com.gpg’
[master 288b379] Removed Amazon/amazonemail@email.com from store.
1 file changed, 0 insertions(+), 0 deletions(-)
delete mode 100644 Amazon/amazonemail@email.com.gpg
zx2c4@laptop ˜ $ pass git push
Counting objects: 9, done.
Delta compression using up to 2 threads.
Compressing objects: 100% (5/5), done.
Writing objects: 100% (7/7), 1.25 KiB, done.
Total 7 (delta 0), reused 0 (delta 0)
To kexec.com:pass-store
```
### Associated Files
| Path | Description |
| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `~/.password-store` | The default password storage directory. |
| `~/.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 `init` command. |
| `~/.password-store/.extensions` | The directory containing extension files. |
### Environment Variables
| Environment Variable | Description |
| ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `$PASSWORD_STORE_DIR` | Overrides the default password storage directory. |
| `$PASSWORD_STORE_KEY` | Overrides the default gpg key identification set by `init`. Keys must not contain spaces and thus use of the hexadecimal key signature is recommended. Multiple keys may be specified separated by spaces. |
| `$PASSWORD_STORE_GPG_OPTS` | Additional options to be passed to all invocations of [GPG](../../cryptography/GPG.md). |
| `$PASSWORD_STORE_X_SELECTION` | Overrides the selection passed to `xclip`, by default clipboard. |
| `$PASSWORD_STORE_CLIP_TIME` | Specifies the number of seconds to wait before restoring the clipboard, by default 45 seconds. |
| `$PASSWORD_STORE_UMASK` | Sets the umask of all files modified by pass, by default 077. |
| `$PASSWORD_STORE_GENERATED_LENGTH` | The default password length if the `pass-length` parameter to generate is unspecified. |
| `$PASSWORD_STORE_CHARACTER_SET` | The character set to be used in password generation for generate. This value is to be interpreted by `tr`. |
| `$PASSWORD_STORE_CHARACTER_SET_NO_SYMBOLS` | The character set to be used in no-symbol password generation for generate, when `--no-symbols`, `-n` is specified. This value is to be interpreted by `tr`. |
| `$PASSWORD_STORE_ENABLE_EXTENSIONS` | This environment variable must be set to "true" for extensions to be enabled. |
| `$PASSWORD_STORE_EXTENSIONS_DIR` | The location to look for executable extension files, by default `$PASSWORD_STORE_DIR/.extensions`. |
| `$PASSWORD_STORE_SIGNING_KEY` | If this environment variable is set, then all `.gpg-id` files and non-system extension files must be signed using a detached signature using the GPG key specified by the full 40 character upper-case fingerprint in this variable. If multiple fingerprints are specified, each separated by a whitespace character, then signatures must match at least one. The `init` command will keep signatures of `.gpg-id` files up to date. |
| `$EDITOR` | The location of the text editor used by edit. |
## Data Organization
### Usernames, Passwords, PINs, Websites, Metadata, et cetera
The password store does not impose any particular schema or type of organization of your data, as it is simply a flat text file, which can contain arbitrary data. Though the most common case is storing a single password per entry, some power users find they would like to store more than just their password inside the password store, and additionally store answers to secret questions, website URLs, and other sensitive information or metadata. Since the password store does not impose a scheme of it's own, you can choose your own organization. There are many possibilities.
One approach is to use the multi-line functionality of pass (`--multiline` or `-m` in `insert`), and store the password itself on the first line of the file, and the additional information on subsequent lines. For example, `Amazon/bookreader` might look like this:
```
Yw|ZSNH!}z"6{ym9pI
URL: *.amazon.com/*
Username: AmazonianChicken@example.com
Secret Question 1: What is your childhood best friend's most bizarre superhero fantasy? Oh god, Amazon, it's too awful to say...
Phone Support PIN #: 84719
```
_This is the preferred organzational scheme used by the author._ The `--clip` / `-c` options will only copy the first line of such a file to the clipboard, thereby making it easy to fetch the password for login forms, while retaining additional information in the same file.
Another approach is to use folders, and store each piece of data inside a file in that folder. For example `Amazon/bookreader/password` would hold bookreader's password inside the `Amazon/bookreader` directory, and `Amazon/bookreader/secretquestion1` would hold a secret question, and `Amazon/bookreader/sensitivecode` would hold something else related to bookreader's account. And yet another approach might be to store the password in `Amazon/bookreader` and the additional data in `Amazon/bookreader.meta`. And even another approach might be use multiline, as outlined above, but put the URL template in the filename instead of inside the file.
The point is, the possibilities here are extremely numerous, and there are many other organizational schemes not mentioned above; you have the freedom of choosing the one that fits your workflow best.
## Extensions for `pass`
In order to faciliate the large variety of uses users come up with, `pass` supports extensions. Extensions installed to `/usr/lib/password-store/extensions` are always enabled. Extensions installed to `~/.password-store/.extensions/COMMAND.bash` are enabled if the `$PASSWORD_STORE_ENABLE_EXTENSIONS` environment variable is `true`.
The community has produced many such extensions:
- [pass-tomb](https://github.com/roddhjav/pass-tomb): manage your password store in a [Tomb](./tomb.md)
- [pass-update](https://github.com/roddhjav/pass-update): an easy flow for updating passwords
- [pass-import](https://github.com/roddhjav/pass-import): a generic importer tool from other password managers
- [pass-extension-tail](https://github.com/palortoff/pass-extension-tail): a way of printing only the tail of a file
- [pass-otp](https://github.com/tadfisher/pass-otp): support for one-time-password (OTP) tokens