archive-gh-me/gopass
1
0
Fork 0
mirror of https://github.com/gopasspw/gopass.git synced 2025-12-08 19:24:54 +00:00
Code Issues Projects Releases Wiki Activity

updating docs (#384)

Browse Source
This commit is contained in:
James 2017-10-06 13:46:59 -04:00 committed by Dominik Schulz
parent ea131b750f
commit 97a5c3653d
8 changed files with 185 additions and 264 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

37
README.md
View File

@ -27,9 +27,9 @@ The slightly more awesome Standard Unix Password Manager for Teams. Written in G
> Password management should be simple and follow [Unix philosophy](http://en.wikipedia.org/wiki/Unix_philosophy). With `pass`, each secret lives inside of a `gpg` encrypted file whose filename is the title of the website or resource that requires the secret. These encrypted files may be organized into meaningful folder hierarchies, copied from computer to computer, and, in general, manipulated using standard command line file management utilities. - [passwordstore.org](https://www.passwordstore.org/)
`gopass` is a rewrite of `pass` in [Go](https://golang.org/) with the aim of making it cross-platform and [adding additional features](#features). Our target audience are professional developers and sysadmins (and especially teams of those) who are well versed with a command line interface. One explicit goal for this project is to make it more approachable to non-technical users. We go by the UNIX philosophy and try to do one thing and do it well, providing a stellar user experience and a sane, simple interface.
*gopass* is a rewrite of the *pass* password manager in [Go](https://golang.org/) with the aim of making it cross-platform and [adding additional features](#features). Our target audience are professional developers and sysadmins (and especially teams of those) who are well versed with a command line interface. One explicit goal for this project is to make it more approachable to non-technical users. We go by the UNIX philosophy and try to do one thing and do it well, providing a stellar user experience and a sane, simple interface.
Warning: `gopass` currently works on Ubuntu & macOS. Please feel free to help with others.
Warning: gopass currently works on Ubuntu & macOS. Please feel free to help with others.
## Demo
@ -39,17 +39,17 @@ Warning: `gopass` currently works on Ubuntu & macOS. Please feel free to help wi
Please see [docs/features.md](https://github.com/justwatchcom/gopass/blob/master/docs/features.md) for an extensive list of all features along with several usage examples.
| **Feature** | *pass* | *gopass* | **State** | **Description** |
| ------------------------------- | ------ | -------- | --------- | ------------------------------------------------------------------- |
| **Secure secret storage** | ✔ | ✔ | *stable* | Securely storing secrets encrypted with GPG |
| **Recipient management** | ❌ | ✔ | *beta* | Easily manage multiple users of each store |
| **Multiple stores** | ❌ | ✔ | *beta* | Mount multiple stores in your root store, like file systems |
| **password quality assistance** | ❌ | ✔ | *beta* | Checks existing or new passwords for common flaws |
| **Binary support** | ❌ | ✔ | *alpha* | Special handling of binary files (automatic Base64 encoding) |
| **YAML support** | ❌ | ✔ | *alpha* | Special handling for YAML content in secrets |
| **password leak checker** | ❌ | ✔ | *alpha* | Perform **offline** checks against known leaked passwords |
| **PAGER support** | ❌ | ✔ | *stable* | Automatically invoke a pager on long output |
| **JSON API** | ❌ | ✔ | *alpha* | Allow `gopass` to be used as a native extension for browser plugins |
| **Feature** | *pass* | *gopass* | **State** | **Description** |
| --------------------------- | ------ | -------- | --------- | ----------------------------------------------------------------- |
| Secure secret storage | ✔ | ✔ | *stable* | Securely storing secrets encrypted with GPG |
| Recipient management | ❌ | ✔ | *beta* | Easily manage multiple users of each store |
| Multiple stores | ❌ | ✔ | *beta* | Mount multiple stores in your root store, like file systems |
| password quality assistance | ❌ | ✔ | *beta* | Checks existing or new passwords for common flaws |
| Binary support | ❌ | ✔ | *alpha* | Special handling of binary files (automatic Base64 encoding) |
| YAML support | ❌ | ✔ | *alpha* | Special handling for YAML content in secrets |
| password leak checker | ❌ | ✔ | *alpha* | Perform **offline** checks against known leaked passwords |
| PAGER support | ❌ | ✔ | *stable* | Automatically invoke a pager on long output |
| JSON API | ❌ | ✔ | *alpha* | Allow gopass to be used as a native extension for browser plugins |
## Installation
@ -69,7 +69,7 @@ We aim for compatibility with the [latest stable Go Release](https://golang.org/
## Credit & License
`gopass` is maintained by the nice folks from [JustWatch](https://www.justwatch.com/gopass) and licensed under the terms of the MIT license.
gopass is maintained by the nice folks from [JustWatch](https://www.justwatch.com/gopass) and licensed under the terms of the MIT license.
Maintainers of this repository:
@ -80,10 +80,10 @@ Please refer to the Git commit log for a complete list of contributors.
## Community
`gopass` is developed in the open. Here are some of the channels we use to communicate and contribute:
gopass is developed in the open. Here are some of the channels we use to communicate and contribute:
* IRC: #gopass on [irc.freenode.net](https://freenode.net) ([join via Riot](https://riot.im/app/#/room/#freenode_#gopass:matrix.org))
* Usage mailing list: [gopass-users](https://groups.google.com/forum/#!forum/gopass-users), for discussions around `gopass` usage and community support
* Usage mailing list: [gopass-users](https://groups.google.com/forum/#!forum/gopass-users), for discussions around gopass usage and community support
* Issue tracker: Use the [GitHub issue tracker](https://github.com/justwatchcom/gopass/issues) to file bugs and feature requests. If you need support, please send your questions to [gopass-user](https://groups.google.com/forum/#!forum/gopass-users) or ask on IRC rather than filing a GitHub issue.
## Contributing
@ -92,12 +92,11 @@ We welcome any contributions. Please see the [CONTRIBUTING.md](https://github.co
## Acknowledgements
`gopass` was initially started by Matthias Loibl and Dominik Schulz. The majority of its development has been sponsored by [JustWatch](https://www.justwatch.com/).
gopass was initially started by Matthias Loibl and Dominik Schulz. The majority of its development has been sponsored by [JustWatch](https://www.justwatch.com/).
## Further Documentation
* [Security](https://github.com/justwatchcom/gopass/blob/master/docs/security.md)
* [Security, Known Limitations, and Caveats](https://github.com/justwatchcom/gopass/blob/master/docs/security.md)
* [Configuration](https://github.com/justwatchcom/gopass/blob/master/docs/config.md)
* [Caveats](https://github.com/justwatchcom/gopass/blob/master/docs/caveats.md)
* [FAQ](https://github.com/justwatchcom/gopass/blob/master/docs/faq.md)
* [JSON API](https://github.com/justwatchcom/gopass/blob/master/docs/jsonapi.md)

28
docs/caveats.md
View File

@ -1,28 +0,0 @@
# Known Limitations and Caveats
## GnuPG
`gopass` uses [gpg](https://www.gnupg.org) to encrypt its secrets. This makes it easy to build a software we feel comfortable
trusting our credentials with, but `gpg` isn't known for being the most user-friendly software.
We try to work around some of the usability limitations of `gpg` but we always have to keep the security
goals in mind, so some features have to trade some usability against security and vice-versa.
## git history and local files
Please keep in mind that by default `gopass` stores its encrypted secrets in git. *This is a deviation
from the behavior of `pass`, which does not force you to use `git`.* Furthermore, the decision has some important
properties.
First it means that every user of `gopass` (and any attacker with access to your git repo) has a local
copy with the full history. If we revoke access to a store from an user and re-encrypt the whole store
this user won't be able to access any changed or added secrets but he'll be always able to access to
secrets by checking out old revisions from the repository.
**If you revoke access from a user you SHOULD change all secrets he had access to!**
## Private Keys required
Please note that we try to make it hard to lock yourself out from your secrets.
To ensure that a user is always able to decrypt his own secrets we require you
to have at least the public **and** private part of an recipient key available.

26
docs/config.md
View File

@ -4,29 +4,25 @@
Some configuration options are only available through setting environment variables.
| **Option** | *Type* | Description |
| -------------------- | -------| ----------- |
| `CHECKPOINT_DISABLE` | `bool` | Set to any non-empty value to disable calling the GitHub API when running `gopass version`. |
| `GOPASS_DEBUG` | `bool` | Set to any non-empty value to enable verbose debug output |
| **Option** | **Type** | **Description** |
| -------------------- | ---------| --------------- |
| `CHECKPOINT_DISABLE` | `bool` | Set to any non-empty value to disable calling the GitHub API when running `gopass version`. |
| `GOPASS_DEBUG` | `bool` | Set to any non-empty value to enable verbose debug output |
## Configuration Options
`gopass` create a new configuration file if not already present during startup.
If a config exists it will attempt to parse and load the settings. If this
fails program execution aborts. If `gopass` can not start because of broken
or incompatible config file move it away (make a backup) and start fresh.
During startup, gopass will look for a configuration file at `$HOME/.config/gopass/config.yml`. If one is not present, it will create one. If the config file already exists, it will attempt to parse it and load the settings. If this fails, the program will abort. Thus, if gopass is giving you trouble with a broken or incompatible configuration file, simply rename it or delete it.
All configuration options are also available for reading and writing through
the subcommand `gopass config`.
All configuration options are also available for reading and writing through the subcommand `gopass config`.
* To display all values type: `gopass config`.
* To display a single value type: `gopass config autosync`
* To update a single value type: `gopass config autosync false`
* To display all values: `gopass config`
* To display a single value: `gopass config autosync`
* To update a single value: `gopass config autosync false`
* As many other subcommands this command accepts a `--store` flag to operate on a given sub-store.
This is a list of options available for `gopass`:
This is a list of options available:
| **Option** | *Type* | Description |
| **Option** | **Type** | Description |
| ------------- | -------- | ----------- |
| `askformore` | `bool` | If enabled - it will ask to add more data after use of `generate` command. |
| `autoimport` | `bool` | Import missing keys stored in the pass repo without asking. |

10
docs/faq.md
View File

@ -1,17 +1,15 @@
# FAQ
* *How does gopass relate to HashiCorp vault?* - While [Vault](https://www.vaultproject.io/) is for machines, `gopass` is for humans [#7](https://github.com/justwatchcom/gopass/issues/7)
* *How does gopass relate to HashiCorp vault?* - While [Vault](https://www.vaultproject.io/) is for machines, gopass is for humans [#7](https://github.com/justwatchcom/gopass/issues/7)
* `gopass show secret` displays `Error: Failed to decrypt` - This issue may happen if your gpg setup if broken. On MacOS try `brew link --overwrite gnupg`. You also may need to set `export GPG_TTY=$(tty)` in your `.bashrc` [#208](https://github.com/justwatchcom/gopass/issues/208), [#209](https://github.com/justwatchcom/gopass/issues/209)
* *gopass recpients add fails with Warning: No matching valid key found* - If the key you're trying to add is already in your keyring you may need to trust it. If this is your key run `gpg --edit-key [KEYID]; trust (set to ultimate); quit`, if this is not your key run `gpg --edit-key [KEYID]; lsign; save; quit`
* *How can gopass handle binary data?* - `gopass` is designed not to change to content of the secrets in any way except that it will add a final newline at the end of the secret iff it does not have one already and the output is going to a terminal. This means that the output may mess up your terminal if it's not only text. In this case you should either encoded the secret to text (e.g. base64) before inserting or use the special `gopass binary` subcommand that does that for you.
* *How can gopass handle binary data?* - gopass is designed not to change to content of the secrets in any way except that it will add a final newline at the end of the secret iff it does not have one already and the output is going to a terminal. This means that the output may mess up your terminal if it's not only text. In this case you should either encoded the secret to text (e.g. base64) before inserting or use the special `gopass binary` subcommand that does that for you.
## API Stability
`gopass` is provided as an CLI program, not as a library. While we try to make the
packages usable as libraries we make no guarantees whatsoever with respect to
the API stability. The `gopass` version only reflects changes in the CLI commands.
gopass is provided as an CLI program, not as a library. While we try to make the packages usable as libraries we make no guarantees whatsoever with respect to the API stability. The gopass version only reflects changes in the CLI commands.
If you use `gopass` as a library be sure to vendor it and expect breaking changes.
If you use gopass as a library be sure to vendor it and expect breaking changes.
## Further Reading

155
docs/features.md
View File

@ -2,11 +2,44 @@
## Standard Features
### Data Organization
Before you start using gopass, you should know a little bit about how it stores your data. It's actually really simple! Each password (or secret) will live in its own file. And you can stick related passwords (or secrets) together in a directory. So, for example, if you had 3 laptops and wanted to store the root passwords for all 3, then your file system might look something like the following:
```
.password-store
└── laptops
├── dell.gpg
├── hp.gpg
└── macbook.gpg
```
With this file system, if you typed the `gopass show` command, it would report the following:
```
gopass
└── laptops
├── dell
├── hp
└── macbook
```
In this example, the key for the MacBook is `laptops/macbook`.
gopass does not impose any specific layout for your data. Any key can contain any kind of data. Please note that sensitive data **should not** be put into the name of a secret.
If you plan to use the password store for website credentials or plan to use [browserpass](https://github.com/dannyvankooten/browserpass), you should follow the following pattern for storing passwords:
```
example1.com/username
example2.com/john@doe.com
```
### Initializing a Password Store
After installing `gopass`, the first thing you should do is initialize a password store. (If you are migrating to `gopass` from `pass` and already have a password store, you can skip this step.)
After installing gopass, the first thing you should do is initialize a password store. (If you are migrating to gopass from pass and already have a password store, you can skip this step.)
Note that this document uses the term *password store* to refer to a directory (usually `$HOME/.password-store`) which is managed by `gopass`. This is entirely different from any OS-level credential store, your GPG keyring, or your SSH Keys.
Note that this document uses the term *password store* to refer to a directory that is managed by gopass. This is entirely different from any OS-level credential store, your GPG keyring, or your SSH keys.
To initialize a password store, just do a:
@ -16,13 +49,13 @@ gopass init
This will prompt you for which GPG key you want to associate the store with. Then it will create a `.password-store` directory in your home directory.
If you don't want `gopass` to use this default directory, you can instead initialize a password store with:
If you don't want gopass to use this default directory, you can instead initialize a password store with:
```bash
gopass init --path /custom/path/to/password/store
````
Note that if you have a huge number of GPG keys on the system or if you are running this command from a script, you can also specify the GPG key to use inline. You can do this in three different ways:
If you don't want gopass to prompt you for the GPG key to use, you can specify it inline. For example, this might be useful if you have a huge number of GPG keys on the system or if you are initializing a password store from a script. You can do this in three different ways:
```bash
gopass init gopher@golang.org # By specifying the email address associated with the GPG key
@ -38,13 +71,13 @@ If you already have an existing password store that exists in a Git repository,
gopass clone git@example.com/pass.git
```
This runs `git clone` in the background. If you don't want `gopass` to use the default directory of "$HOME/.password-store", then you can specify an additional parameter:
This runs `git clone` in the background. If you don't want gopass to use the default directory of "$HOME/.password-store", then you can specify an additional parameter:
```bash
gopass clone git@example.com/pass-work.git work # This will initialize the password store in the "$HOME/.password-store-work" directory
```
Please note that all cloned repositories must already have been initialized with `gopass`. (See the previous section for more details.)
Please note that all cloned repositories must already have been initialized with gopass. (See the previous section for more details.)
### Adding Secrets
@ -58,8 +91,8 @@ Let's say you want to create an account.
```bash
$ gopass insert golang.org/gopher
Enter secret for golang.org/gopher: # hidden
Retype secret for golang.org/gopher: # hidden
Enter secret for golang.org/gopher: # hidden on Linux / macOS
Retype secret for golang.org/gopher: # hidden on Linux / macOS
gopass: Encrypting golang.org/gopher for these recipients:
- 0xB5B44266A3683834 - Gopher <gopher@golang.org>
@ -89,9 +122,7 @@ The generated password for golang.org/gopher is:
Eech4ahRoy2oowi0ohl
```
The `generate` command will ask for any missing arguments, like the name of the
secret or the length. If you don't want the password to be displayed use the
`-c` flag to copy it to your clipboard.
The `generate` command will ask for any missing arguments, like the name of the secret or the length. If you don't want the password to be displayed use the `-c` flag to copy it to your clipboard.
### Edit a secret
@ -99,8 +130,7 @@ secret or the length. If you don't want the password to be displayed use the
$ gopass edit golang.org/gopher
```
The `edit` command uses the `$EDITOR` environment variable to start your preferred editor where
you can easily edit multi-line content. `vim` will be the default if `$EDITOR` is not set.
The `edit` command uses the `$EDITOR` environment variable to start your preferred editor where you can easily edit multi-line content. `vim` will be the default if `$EDITOR` is not set.
### Listing existing secrets
@ -116,9 +146,7 @@ gopass
└── user@justwatch.com
```
If your terminal supports colors the output will use ANSI color codes to highlight directories
and mounted sub stores. Mounted sub stores include the mount point and source directory. See
below for more details on mounts and sub stores.
If your terminal supports colors the output will use ANSI color codes to highlight directories and mounted sub stores. Mounted sub stores include the mount point and source directory. See below for more details on mounts and sub stores.
### Show a secret
@ -128,12 +156,9 @@ $ gopass golang.org/gopher
Eech4ahRoy2oowi0ohl
```
The default action of `gopass` is show. It also accepts the `-c` flag to copy the content of
the secret directly to the clipboard.
The default action of `gopass` is show, so the previous command is exactly the same as typing `gopass show golang.org/gopher`. It also accepts the `-c` flag to copy the content of the secret directly to the clipboard.
Since it may be dangerous to always display the password on `gopass` calls, the `safecontent`
setting may be set to `true` to allow one to display only the rest of the password entries by
default and display the whole entry, with password, only when the `-f` flag is used.
Since it may be dangerous to always display the password, the `safecontent` setting may be set to `true` to allow one to display only the rest of the password entries by default and display the whole entry, with password, only when the `-f` flag is used.
#### Copy a secret to the clipboard
@ -149,9 +174,7 @@ Copied golang.org/gopher to clipboard. Will clear in 45 seconds.
$ gopass rm golang.org/gopher
```
`rm` will remove a secret from the store. Use `-r` to delete a whole folder.
Please note that you **can not** remove a folder containing a mounted sub store.
You have to unmount any mounted sub stores first.
`rm` will remove a secret from the store. Use `-r` to delete a whole folder. Please note that you **can not** remove a folder containing a mounted sub store. You have to unmount any mounted sub stores first.
### Moving a secret
@ -173,14 +196,11 @@ $ gopass cp emails/example.com emails/user@example.com
### Auto-Pager
Like other popular open-source projects `gopass` automatically pipe the output
to `$PAGER` if it's longer than one terminal page. You can disable this behavior
by unsetting `$PAGER` or `gopass config nopager true`.
Like other popular open-source projects, gopass automatically pipe the output to `$PAGER` if it's longer than one terminal page. You can disable this behavior by unsetting `$PAGER` or `gopass config nopager true`.
### git auto-push and auto-pull
If you want gopass to always push changes in git to your default remote (origin)
enable autosync:
If you want gopass to always push changes in git to your default remote server (origin), enable autosync:
```bash
$ gopass config autosync true
@ -188,8 +208,7 @@ $ gopass config autosync true
### Check Passwords for Common Flaws
gopass can check your passwords for common flaws, like being too short or coming
from a dictionary.
gopass can check your passwords for common flaws, like being too short or coming from a dictionary.
```bash
$ gopass audit
@ -198,13 +217,9 @@ Detected weak secret for 'golang.org/gopher': Password is too short
### Check Passwords against leaked passwords
gopass can assist you in checking your passwords against those included in recent
data breaches. Right now this you still need to download and unpack those dumps
yourself, but gopass can take care of the rest.
gopass can assist you in checking your passwords against those included in recent data breaches. Right now this you still need to download and unpack those dumps yourself, but gopass can take care of the rest.
First go to [haveibeenpwned.com/Passwords](https://haveibeenpwned.com/Passwords) and download
the dumps. Then unpack the 7-zip archives somewhere. Note that full path to those
files and provide it to gopass in the environment variable `HIBP_DUMPS`.
First go to [haveibeenpwned.com/Passwords](https://haveibeenpwned.com/Passwords) and download the dumps. Then unpack the 7-zip archives somewhere. Note that full path to those files and provide it to gopass in the environment variable `HIBP_DUMPS`.
```bash
$ HIBP_DUMPS=/tmp/pwned-passwords-1.0.txt gopass audit hibp
@ -212,10 +227,7 @@ $ HIBP_DUMPS=/tmp/pwned-passwords-1.0.txt gopass audit hibp
### Support for Binary Content
gopass provides secure and easy support for working with binary files through the
`gopass binary` family of subcommands. One can copy or move secret from or to
the store. gopass will attempt to securely overwrite and remove any secret moved
to the store.
gopass provides secure and easy support for working with binary files through the `gopass binary` family of subcommands. One can copy or move secret from or to the store. gopass will attempt to securely overwrite and remove any secret moved to the store.
```bash
# copy file "/some/file.jpg" to "some/secret.b64" in the store
@ -229,16 +241,7 @@ $ gopass binary sha256 my/private.key
### Multiple Stores
gopass supports multi-stores that can be mounted over each other like filesystems
on Linux/UNIX systems.
To add an mount point to an existing store add an entry to the `mounts` object
of the store.
gopass tries to read its configuration from `$HOME/.config/gopass/config.yml` if present.
You can override this location by setting `GOPASS_CONFIG` to another location.
Mounting new stores can be done through gopass:
gopass supports multi-stores that can be mounted over each other like filesystems on Linux/UNIX systems. Mounting new stores can be done through gopass:
```bash
# Mount a new store
@ -251,29 +254,24 @@ $ gopass mounts remove test
You can initialize a new store using `gopass init --store mount-point --path /path/to/store`.
Where possible sub stores are supported transparently through the path to the
secret. When specifying the name of a secret it's matched against any mounted
sub stores and the given action is executed on this store.
Where possible sub stores are supported transparently through the path to the secret. When specifying the name of a secret it's matched against any mounted sub stores and the given action is executed on this store.
Commands that don't accept an secret name, e.g. `gopass recipients add` or
`gopass init` usually accept a `--store` parameter. Please check the help output
of each command for more information, e.g. `gopass help init` or
`gopass recipients help add`.
Commands that don't accept an secret name, e.g. `gopass recipients add` or `gopass init` usually accept a `--store` parameter. Please check the help output of each command for more information, e.g. `gopass help init` or `gopass recipients help add`.
Commands that support the `--store` flag:
| **Command** | *Example* | Description |
| ----------- | --------- | ----------- |
| `gopass git` | `gopass git --store=foo push origin master` | Push all changes in the sub store *foo* to master
| `gopass git init` | `gopass git init --store=foo` | Initialize git in the sub store *foo*
| `gopass init` | `gopass init --store=foo` | Initialize and mount the new sub store *foo*
| `gopass recipients add`| `gopass recipients add --store=foo GPGxID` | Add the new recipient *GPGxID* to the store *foo*
| `gopass recipients remove` | `gopass recipients remove --store=foo GPGxID` | Remove the existing recipients *GPGxID* from the store *foo*
| `gopass config` | `gopass config --store=foo autosync false` | Set the config flag `autosync` to `false` for the store *foo*
| **Command** | **Example** | **Description** |
| -------------------------- | --------------------------------------------- | --------------- |
| `gopass git` | `gopass git --store=foo push origin master` | Push all changes in the sub store *foo* to master |
| `gopass git init` | `gopass git init --store=foo` | Initialize git in the sub store *foo* |
| `gopass init` | `gopass init --store=foo` | Initialize and mount the new sub store *foo* |
| `gopass recipients add` | `gopass recipients add --store=foo GPGxID` | Add the new recipient *GPGxID* to the store *foo* |
| `gopass recipients remove` | `gopass recipients remove --store=foo GPGxID` | Remove the existing recipients *GPGxID* from the store *foo* |
| `gopass config` | `gopass config --store=foo autosync false` | Set the config flag `autosync` to `false` for the store *foo* |
### Directly edit structured secrets aka. YAML support
`gopass` supports directly editing structured secrets (only simple key-value maps so far).
gopass supports directly editing structured secrets (only simple key-value maps so far).
```bash
$ gopass generate -n foo/bar 12
@ -291,8 +289,7 @@ baz: zab
### Edit the Config
`gopass` allows editing the config from the command-line. This is similar to how `git` handles `config`
changes through the command-line. Any change will be written to the configured `gopass` config file.
gopass allows editing the config from the command-line. This is similar to how git handles config changes through the command-line. Any change will be written to the configured gopass config file.
```bash
$ gopass config
@ -333,27 +330,21 @@ gopass
└── 0xB1C7DF661ABB2C1A - Someone <someone@example.com>
```
Running `gopass recipients` will also try to load and save any missing GPG keys
from and to the store.
Running `gopass recipients` will also try to load and save any missing GPG keys from and to the store.
The commands manipulating recipients, i.e. `gopass recipients add` and
`gopass recipients remove` accept a `--store` flag that expects the
*name of a mount point* to operate on this mounted sub store.
The commands manipulating recipients, i.e. `gopass recipients add` and `gopass recipients remove` accept a `--store` flag that expects the *name of a mount point* to operate on this mounted sub store.
### Debugging
To debug `gopass`, set the environment variable `GOPASS_DEBUG` to `true`.
To debug gopass, set the environment variable `GOPASS_DEBUG` to `true`.
### Restricting the characters in generated passwords
To restrict the characters used in generated passwords set `GOPASS_CHARACTER_SET` to
any non-empty string. Please keep in mind that this can considerably weaken the
strength of generated passwords.
To restrict the characters used in generated passwords set `GOPASS_CHARACTER_SET` to any non-empty string. Please keep in mind that this can considerably weaken the strength of generated passwords.
### In-place updates to existing passwords
Running `gopass [generate|insert] foo/bar` on an existing entry `foo/bar` will only update
the first line of the secret, leaving any trailing data in place.
Running `gopass [generate|insert] foo/bar` on an existing entry `foo/bar` will only update the first line of the secret, leaving any trailing data in place.
### Disabling Colors
@ -361,13 +352,13 @@ Disabling colors is as simple as setting `GOPASS_NOCOLOR` to `true`.
### Password Templates
With `gopass` you can create templates which are searched when executing `gopass edit` on a new secret. If the folder, or any parent folder, contains a file called `.pass-template` it's parsed as a Go template, executed with the name of the new secret and an auto-generated password and loaded into your `$EDITOR`.
With gopass you can create templates which are searched when executing `gopass edit` on a new secret. If the folder, or any parent folder, contains a file called `.pass-template` it's parsed as a Go template, executed with the name of the new secret and an auto-generated password and loaded into your `$EDITOR`.
This makes it easy to use templates for certain kind of secrets such as database passwords.
### JSON API
`gopass jsonapi` enables communication with `gopass` via json messages. This is particularly useful for browser plugins like [gopassbridge](https://github.com/martinhoefling/gopassbridge) running `gopass` as native app. More details can be found in [docs/jsonapi.md](docs/jsonapi.md).
`gopass jsonapi` enables communication with gopass via JSON messages. This is particularly useful for browser plugins like [gopassbridge](https://github.com/martinhoefling/gopassbridge) running gopass as native app. More details can be found in [docs/jsonapi.md](docs/jsonapi.md).
## Roadmap

6
docs/jsonapi.md
View File

@ -2,9 +2,7 @@
## Overview
The API follows specification for native messaging from [Mozilla](https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Native_messaging) and [Chrome](https://developer.chrome.com/apps/nativeMessaging).
Each json-utf8 encoded message is prefixed with a 32 bit integer specifying the length of the message.
Communication is performed via stdin/stdout. Currently, only a single request is repsonded `gopass jsonapi` call.
The API follows specification for native messaging from [Mozilla](https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Native_messaging) and [Chrome](https://developer.chrome.com/apps/nativeMessaging). Each json-utf8 encoded message is prefixed with a 32-bit integer specifying the length of the message. Communication is performed via stdin/stdout.
**WARNING**: This API **MUST NOT** be exposed over the network to remote hosts. **No authentication is performed** and the only safe way is to communicate via stdin/stdout as you do in your terminal.
@ -80,6 +78,6 @@ If an uncaught error occurs, the stringified error message is send back as respo
```json
{
"error": "Some error occured with fancy message"
"error": "Some error occurred with fancy message"
}
```

70
docs/security.md
View File

@ -1,46 +1,52 @@
## Security
# Security, Known Limitations, and Caveats
This project aims to provide a secure and dependable credential store that can
be used by individuals or teams.
This project aims to provide a secure and dependable credential store that can be used by individuals or teams.
We acknowledge that designing and implementing bullet-proof cryptography is very
hard and try to leverage existing and proven technology instead of rolling
our own implementations.
We acknowledge that designing and implementing bullet-proof cryptography is very hard and try to leverage existing and proven technology instead of rolling our own implementations.
### Ultimate Goals of Security
## Security Goals
* Confidentially - Ensure that only authorized parties can understand the data.
gopass does only try to protect the content of the secrets.
Neither their presence nor their names. Care must be taken not to
disclose any confidential information through the name of the secrets.
* Authentication - Ensure that whoever supplies some secret if an authorized party.
gopass fully relies on GnuPG in this regard.
* Integrity - Ensure that only authorized parties are allowed to modify data.
Currently gopass makes no attempt at protecting the integrity of a store.
However we plan to do this in the future.
* Nonrepudiation - Ensure that the involved parties actually transmitted and
received messages. gopass makes not attempt to ensure this.
* **Confidentially** - Ensure that only authorized parties can understand the data.
* gopass attempts to protect the content of the secrets that it manages using [GNU Privacy Guard](#gnu-privacy-guard).
* gopass does NOT protect the presence of the secrets OR the names of the secrets. Care must be taken not to disclose any confidential information through the
name of the secrets.
* **Integrity** - Ensure that only authorized parties are allowed to modify data.
* gopass makes no attempt at protecting the integrity of a store. However, we plan to do this in the future.
* **Availability** - Secrets must always be readable by exactly the specified recipients.
* gopass provides fairly good availability due to its decentralized nature. For example, if your local password store is corrupted or destroyed, you can easily clone it from the Git server again. Conversely, if the Git server is offline or is destroyed, you (and your teammates) have a complete copy of all of the secrets on your local machine(s).
* **Non-repudiation** - Ensure that the involved parties actually transmitted and received messages.
* gopass makes no attempt to ensure this.
### Additional Usability Goals
* Availability - Secrets must always be readable by exactly the specified recipients.
* Sensible Defaults - This project shall try to make the right things easy to do and make the wrong things hard to do.
### Password Store Initialization
## Threat Model
gopass only uses GPG for encrypting data. GPG needs to be properly set up before using gopass.
The user is responsible for distributing and importing the necessary public keys. Knowledge
of the web of trust model of GPG is assumed and necessary.
The threat model of gopass assumes there are no attackers on your local machine. Currently no attempts are taken to verify the integrity of the password store. We plan on using signed git commits for this. Anyone with access to the git repository can see which secrets are stored inside the store, but not their content.
### Generating Passwords
## GNU Privacy Guard
Password generation uses the same approach as the popular tool `pwgen`.
It reads uses the `crypto/rand` to select random characters from the selected
character classes.
gopass uses [GNU Privacy Guard](https://www.gnupg.org) (or GPG for short) to encrypt its secrets. This makes it easy to build a software we feel comfortable
trusting our credentials with. The first production release of GPG was on [September 9th, 1999](https://en.wikipedia.org/wiki/GNU_Privacy_Guard#History) and it is mature enough for most security experts to place a high degree of confidence in the software.
### Threat model
With that said, GPG isn't known for being the most user-friendly software. We try to work around some of the usability limitations of GPG but we always do so keeping security in mind. This means that, in some cases, the project carefully makes some security trade-offs in order to achieve better usability.
The threat model of gopass assumes there are no attackers on your local machine. Currently
no attempts are taken to verify the integrity of the password store. We plan on using
signed git commits for this. Anyone with access to the git repository can see which
secrets are stored inside the store, but not their content.
Since gopass uses GPG to encrypt data, GPG needs to be properly set up beforehand. (GPG installation is covered in the [gopass installation documentation](https://github.com/justwatchcom/gopass/blob/master/docs/setup.md).) However, basic knowledge of how [public-key cryptography](https://en.wikipedia.org/wiki/Public-key_cryptography) and the [web of trust model](https://en.wikipedia.org/wiki/Web_of_trust) is assumed and necessary.
## Generating Passwords
Password generation uses the same approach as the popular tool `pwgen`. It reads uses the `crypto/rand` to select random characters from the selected character classes.
## git history and local files
Please keep in mind that by default, gopass stores its encrypted secrets in git. *This is a deviation from the behavior of `pass`, which does not force you to use `git`.* This has important implications.
First, it means that every user of gopass (and any attacker with access to your git repo) has a local copy with the full history. If we revoke access to a store from an user and re-encrypt the whole store this user won't be able to access any changed or added secrets but he'll be always able to access to
secrets by checking out old revisions from the repository.
**If you revoke access from a user you SHOULD change all secrets he had access to!**
## Private Keys Required
Please note that we try to make it hard to lock yourself out from your secrets. To ensure that a user is always able to decrypt his own secrets, gopass requires that the user has at least one private key available (that matches the current public keys on file for the password store).

117
docs/setup.md
View File

@ -11,11 +11,10 @@
### Download and Install Dependencies
`gopass` needs some external programs to work:
gopass needs some external programs to work:
* `gpg`
* `git`
* An external editor (using `vim` by default)
#### Ubuntu & Debian
@ -42,9 +41,9 @@ brew install gnupg2 git
* Download and install [GPG4Win](https://www.gpg4win.org/).
* Download and install [the Windows git installer](https://git-scm.com/download/win).
### Setup a GPG key pair
### Set up a GPG key pair
`gopass` depends on `gpg` for encryption and decryption. You **must** have a
gopass depends on the `gpg` program for encryption and decryption. You **must** have a
suitable key pair. To list your current keys, you can do:
```bash
@ -71,25 +70,11 @@ Now, you have created a public and private key pair. If you don't know what that
* ["git + gpg, know thy commits" at coderwall](https://coderwall.com/p/d3uo3w/git-gpg-know-thy-commits)
* ["Generating a new GPG key" by GitHub](https://help.github.com/articles/generating-a-new-gpg-key/)
### Securing Your Editor
Various editors may store temporary files outside of the secure working directory
when editing secrets. It's advised to check and disable this behavior for
your editor of choice.
For `vim` on Linux, the following setting may be helpful:
```
au BufNewFile,BufRead /dev/shm/gopass.* setlocal noswapfile nobackup noundofile
```
## Installation Steps
Depending on your operating system, you can either use a package manager,
download a pre-built binary, or install from source. If you have a working Go
development environment, we recommend building from source.
Depending on your operating system, you can either use a package manager, download a pre-built binary, or install from source. If you have a working Go development environment, we recommend building from source.
#### macOS
### macOS
If you haven't already, install [homebrew](http://brew.sh). And then:
@ -98,9 +83,9 @@ brew tap justwatchcom/gopass
brew install gopass
```
Alternatively, you can grab the appropriate darwin release from the repository [releases page](https://github.com/justwatchcom/gopass/releases).
Alternatively, you can install gopass from the appropriate darwin release from the repository [releases page](https://github.com/justwatchcom/gopass/releases).
#### Ubuntu & Debian
### Ubuntu & Debian
First, find the latest .deb release from the repository [releases page](https://github.com/justwatchcom/gopass/releases). Then, download and install it:
@ -109,15 +94,13 @@ wget [the URL of the latest .deb release]
sudo dpkg -i gopass-1.2.0-linux-amd64.deb
```
#### Windows
### Windows
**WARNING**: Windows is not yet officially supported. We try to support it in
the future. These are steps are only meant to help you setup `gopass` on Windows
so you can provide us with feedback about the current state of our Windows support.
**WARNING**: Windows is not yet officially supported. We try to support it in the future. These are steps are only meant to help you setup gopass on Windows so you can provide us with feedback about the current state of our Windows support.
Download and install a suitable Windows build from the repository [releases page](https://github.com/justwatchcom/gopass/releases).
#### Installing from Source
### Installing from Source
If you have [Go](https://golang.org/) already installed, you can use `go get` to automatically download the latest version:
@ -129,40 +112,48 @@ If `$GOPATH/bin` is in your `$PATH`, you can now run `gopass` from anywhere on y
## Optional Post-Installation Steps
#### Migrating from `pass` to `gopass`
### Securing Your Editor
If you are migrating from `pass` to `gopass`, it may be helpful to link it to `pass` so that you can use it as a drop-in replacement for `pass`. For example, assuming `$HOME/bin/` exists and is present in your `$PATH`:
Various editors may store temporary files outside of the secure working directory when editing secrets. We advise you to check and disable this behavior for your editor of choice.
For `vim` on Linux, the following setting may be helpful:
```
au BufNewFile,BufRead /dev/shm/gopass.* setlocal noswapfile nobackup noundofile
```
### Migrating from pass to gopass
If you are migrating from pass to gopass, you can simply use your existing password store and everything should just work. Furthermore, it may be helpful to link the gopass binary so that you can use it as a drop-in replacement. For example, assuming `$HOME/bin/` exists and is present in your `$PATH`:
```bash
ln -s $GOPATH/bin/gopass $HOME/bin/pass
```
#### Enable Bash / Z Shell Autocompletion
### Migrating to gopass from Other Password Stores
Run one of the following commands for your shell and you should have
autocompletion for subcommands like `gopass show`, `gopass ls` and others.
Before migrating to gopass, you may have been using other password managers (such as [KeePass](https://keepass.info/), for example). If you were, you might want to import all of your existing passwords over. Because gopass is fully backwards compatible with pass, you can use any of the existing migration tools found under the "Migrating to pass" section of the [official pass website](https://www.passwordstore.org/).
### Enable Bash / Z Shell Autocompletion
If you use Bash or Z Shell, you can run one of the following commands to enable autocompletion for subcommands like `gopass show`, `gopass ls` and others.
```
source <(gopass completion bash)
source <(gopass completion zsh)
```
#### Enable fish completion
### Enable fish completion
Experimental [fish](https://fishshell.com/) shell completion is available.
Copy the file `fish.completion` to `~/.config/fish/completions/gopass.fish`
and start a new shell.
If you use the [fish](https://fishshell.com/) shell, you can enable experimental shell completion. Copy the file `fish.completion` to `~/.config/fish/completions/gopass.fish` and start a new shell.
Since writing fish completion scripts is not yet supported by the CLI library we
use, this completion script is missing a few features. Feel free to contribute
if you want to improve it.
Since writing fish completion scripts is not yet supported by the CLI library we use, this completion script is missing a few features. Feel free to contribute if you want to improve it.
#### dmenu / rofi support
### dmenu / rofi support
In earlier versions `gopass` supported [dmenu](http://tools.suckless.org/dmenu/).
We removed this and encourage you to call dmenu yourself now.
In earlier versions gopass supported [dmenu](http://tools.suckless.org/dmenu/). We removed this and encourage you to call dmenu yourself now.
This also makes it easier to call `gopass` with e.g. [rofi](https://github.com/DaveDavenport/rofi).
This also makes it easier to call gopass with [rofi](https://github.com/DaveDavenport/rofi), for example.
```bash
# Simply copy the selected password to the clipboard
@ -171,51 +162,21 @@ gopass ls --flat | dmenu | xargs --no-run-if-empty gopass show -c
gopass ls --flat | dmenu | xargs --no-run-if-empty gopass show | head -n 1 | xdotool type --clearmodifiers --file -
```
#### Migrating to `gopass` from Other Password Stores
### Storing and Syncing your Password Store with Google Drive / Dropbox / etc.
Because `gopass` is fully backwards compatible with `pass`, you can use any of the existing migration tools found under the "Migrating to pass" section of the [official pass website](https://www.passwordstore.org/).
Please be warned that using cloud-based storage may negatively impact to confidentially of your store. However, if you wish to use one of these services, you can do so.
### Data Organization
Your data in `gopass` loosely resembles an file system. You need to have at least one
root store but you can mount as many sub-stores (think of volumes) under the root volume.
The stores do not impose any specific layout for your data. Any `key` can contain any kind of data.
Please note that sensitive data **should not** be put into the name of a secret.
If you mainly use a store for website logins or plan to use
[browserpass](https://github.com/dannyvankooten/browserpass) you should follow
the following pattern for storing your credentials:
```
example.org/user
example.com/john@doe.com
```
#### Storing and Syncing your Password Store with Google Drive / Dropbox / etc.
Please be warned that using a cloud-based storage _drive_ may negatively impact
to confidentially of your store, but if you wish to use one of these services
you can do so.
For example, if using [Google Drive](https://drive.google.com):
For example, to use gopass with [Google Drive](https://drive.google.com):
```bash
cd
gopass init --nogit
mv .password-store/ "Google Drive/Password-Store"
gopass config path "~/Google Drive/Password-Store"
```
### Using other GUIs with `gopass`
### Download a GUI
Because `gopass` is fully backwards compatible with `pass`, you can use some existing interfaces:
Because gopass is fully backwards compatible with pass, you can use some existing graphical user interfaces / frontends:
* Android - [PwdStore](https://github.com/zeapo/Android-Password-Store)
* iOS - [Pass for iOS](https://github.com/davidjb/pass-ios#readme)