Domain Driven Architecture

Gopass Quick-Reference

Autor: A Zwick

January 29, 2020

Tags: password-manager, howto, reference, gopass

Gopass is a password-manager suitable for individuals and especially for teams. Key features include:

Encrypted storage of secrets (each secret is stored in an own files)
Encryption by GPG (GnuPG)
Versioning by GIT (in git repositories)

A secret in gopass can consist of a single value, such as a password, or multiple fields containing additional information like a username, URL, etc.

File structure of gopass

Gopass stores all secrets in separate files in a directory structure. The files are encrypted for certain gpg-ids. The gpg-ids used for the encryption are stored in files named .gpg-id.
More precisely, a file .gpg-id contains all public gpg-ids (in fact their fingerprints) which are used to encrypt all the files in the same folder and all subfolders. If there is another .gpg-id file in a subfolder, it "overwrites" on its turn the keys of this subfolder and sub-subfolders.

A simple gopass folder tree might look like:

gopass     (gopass root)
 ├─ team      (a team store resp. mount)
 |   ├─ .public-keys  (contains the team members' public keys)
 |   |    └─ 8C6B83F071FBF4D45232FE9D4700C1   (contains public key; filename is fingerprint of key)
 |   ├─ .gpg-id   (contains the team's gpg ids)
 |   └─ server-pw
 └─ personal  (a personal store resp. mount)
     ├─ .gpg-id   (contains only the personal id(s))
     └─ email-pw

The default root folder is: /.password-store/

Gopass stores its configuration in a config.yml file, in Linux it is usually found in folder ~/.config/gopass/ This config-file can be handy for checking some config details, or - at own risk (!) - to make manual config changes.

The public keys of the recipients are stored in folder .public-keys/ in each store/mount.

Prerequisites

GnuPG (aka gpg) needs to be installed. If not, install (depending on your environment) e.g. with: sudo apt install gpg
gpg keys must be available
- check with: gpg -k for existing keys
- if none are available (or you want to create new ones), use: gpg --full-gen-key, for details see the corresponding paragraph below.

Setup

Install as described on: https://www.gopass.pw/ (WARNING: The package "gopass" of the official Debian repositories is not related to this gopass. So, DO NOT use sudo apt-get install gopass directly, unless you want to install the "other" gopass.)
Initialization:
- Use gopass init <gpg-id> for initialization in the default location (i.e. ~/.password-store/), where <gpg-id> is the fingerprint of your public gpg-key.
- or initialize in another location with: gopass init -p <folder-path> <gpg-id>

Update Gopass

If you have installed gopass with a package manager, you can use the same package manager to update gopass. If gopass has been installed manually, you'd need to re-install with a newer version in order to update.

Gopass Commands

Gopass help

gopass -h

List all secrets (i.e. the secret names, not the actual secrets):

gopass ls

To show a secret, use the secret name or complete secret path:

gopass <SECRET-NAME OR PATH>
# Example
gopass mysecret
gopass mystore/mysecret

To list secrets of a particular store or subfolder, use e.g. for store mystore

gopass mystore
gopass mystore/mysecret

Insert / add a secret

gopass insert <secret-path>
# Example
gopass insert mystore/mysecret

Edit a secret

gopass edit <secret>
# Example
gopass edit mystore/mysecret

Copy secret to clipboard

gopass -c <secret>
# Examples
gopass -c mysecret
gopass -c mystore/mysecret

Delete secret

gopass rm <secret>
# Example
gopass rm mystore/mysecret

Move secret

gopass mv <original-secret-path> <new-secret-path>
# Example: 
gopass mv mystore/myfolder/mysecret mystore/otherfolder/movedSecret

Search secret name or excrypted secret

Search for secret names (for search within the encrypted secrets, see command gopass grep below). This search is case-insensitive.

gopass search <part of secret name>
# Example
gopass search my-partial-secret-name

Search within encrypted secrets. It can only find secrets which you are able to decrypt (you will be prompted for the passphrase of your private key):

gopass grep <text to find>
# Example: 
gopass grep my-username

Generate / rotate a secret

Generating resp. rotating a secret can be done by editing it manually or by using generate:

gopass generate <path to secret> <optional length>
# Example: 
gopass generate my-store/my-secret
gopass generate my-store/my-secret 25

The generate command replaces the first line of a secret with a newly generated one. The content of other lines is not changed, but the lines below the first one might be reordered.

Passwords are generated by default with alphanumeric characters without symbols. To include symbols you can use option "-s", example:

gopass generate -s my-store/my-secret 25

Using stores (aka mounts)

Gopass supports multiple repositories aka mounts resp. stores.

Stores are very handy to manage different sets of secrets in different git repositories. E.g. you can use a personal store and a store for all team members.

List mounted stores

gopass mounts

Add a store

A store (repository) can be created and mounted (i.e. added to gopass) by:

gopass init --store <store-name> --path <path>
Example: gopass init --store personal --path ~/personal-path

Or mount a store directly from a remote git repo:

gopass clone <git-url> <store-name> --sync gitcli
Example: gopass clone git@gitserver.com/myRepo/credentials.git personal --sync gitcli

Or you can mount an already existing local store:

gopass mounts add <store name> <path to local store>
Example: gopass mounts add mystore ~/repo/personal/store

Remove a store

gopass mounts unmount <store-name>
Example: gopass mounts unmount personal

Manage team members and keys

List members resp. keys

Check the members for whom the secrets are encrypted:

gopass recipients
gopass recipients <store name>

Shows the recipients for all stores resp. for a specific store.

This command only shows "top-level" recipients, does not show recipients of a subfolder, if other recipients were defined in a subfolder's .gpg-id file.

Add / remove / replace a key

Prerequisite for adding a key: Generate a new key (as describe above).

Only a team member with a valid key for the respective store can add a new key resp remove a key by:

gopass recipients add <FINGERPRINT or EMAIL>
gopass recipients rm <FINGERPRINT or EMAIL>

If several stores exist, gopass will prompt to select a store. Alternatively you can specify the store directly:

gopass recipients add --store <mystore> <NEW FINGERPRINT or EMAIL>
gopass recipients rm --store <mystore> <OLD FINGERPRINT or EMAIL>

A message like Not using key <FINGERPRINT> for encryption. might be shown if the new public key was not imported yet (by the person who has added the fingerprint). This can be solved by the following steps.

Run:

gopass sync

by:

the person who has added the fingerprint -> publishing his changes to remote
(if a key was added) the owner of the new key -> storing new public key (in folder .public-keys of the store) with its fingerprint as filename
all other team members to import all changes including the new public key.

Manual import of key

Alternatively a public key can always be imported manually by

gpg --import michaels_key.pub.asc

Get fingerprints

You can get the fingerprint of a key by:

gpg --fingerprint <keyname>

or list all keys including the fingerprints:

gpg --list-public-keys --with-fingerprint --with-colons

Enable auto-completion in bash

echo "source <(gopass completion bash)" >> ~/.bashrc

Gopass Bridge

If you are already using gopass for storing your passwords, Gopass Bridge is a handy tool for easy entering passwords into webpages.

Installation

In order to use the Gopass Bridge you need

gopass-jsonapi
the Gopass Bridge browser plugin

Use the steps below to install and configure gopass-jsonapi and Gopass Bridge for Ubuntu per cli.
(alternatively follow the description on: https://github.com/gopasspw/gopass-jsonapi/blob/main/README.md)

Download the appropriate version of the gopass-jsonapi e.g. for gopass 1.12 (find out by gopass -version) by:
curl -L https://github.com/gopasspw/gopass-jsonapi/releases/download/v1.11.1/gopass-jsonapi_1.11.1_linux_amd64.deb --output jsonapi.deb
Note: for other gopass versions, see: https://github.com/gopasspw/gopass-jsonapi#installation
Install gopass-jsonapi sudo dpkg -i jsonapi.deb
Configure gopass-jsonapi by gopass-jsonapi configure and answer the subsequent questions.
Install the browser plugin
- Firefox Extension
- or Chrome / Chromium Extension
Ensure your gopass entries follow this format (password separated with — from username in separate lines):
```
<password>
---
username: <username>
url: https://url-of-these-credentials.com
```

url is optional.

Usage

Click on Gopass Bridge Icon in your browser and enter the credential name, e.g. if the password has been stored in path /web/personal/github just enter git or another substring in order to search.