Pass, a simple UNIX password manager

Published: 2019-12-15

Pass is a password manager adhering to the KISS Unix philosophy. It builds on existing tools (GnuPG and git e.g.) and stores your password as simple GPG encrypted files in its tree. There are multiple clients and extensions available and it allows you to manage your passwords transparently. The tool itself is a Bash script, so you can easily inspect the code. Most Linux distributions offer pass as a binary package, so you can get started right away.

Initial setup

Pass allows you to use a git repo (be it local or remote) as your backend. I already have a few git repos on my Odroid XU4 at home, because multiple devices need access to them, so that's where the Pass git repository ends up as well. If you'd like to sync your passwords remotely, you can do something similar and e.g. set up a VPN to your home network. Your clients do not need to be online for access to your password vault; they do need to be online to synchronise though.

Remote repo setup

If all you need is a local setup without git, just skip the pass git [...] commands below. First, we'll initialise the git repo on the local server. SSH in and create your repo:

$ ssh odroidxu4
$ git init --bare ~/git/pass-store.git

That's all there's to it.

Password vault setup on your local client

Now that you have the git repository ready, decide what GPG key you'll use to encrypt your passwords. At this point, allow me to point out that using a keyring will greatly facilitate this. If you're managing a lot of SSH keys, you're probably already using one. If not, examples on Linux are Gnome Keyring and KDE Wallet. Without a keyring, you'll have to unlock your GPG key every single time you manipulate a password entry. That's a fast lane to RSI.

With that in mind, let's create your password vault. The first command will ask you to unlock your GPG key if the key isn't cached by your keyring already. Provide the name of the key you intend to use between double quotes.

$ pass init "Don Quichote (Main key)"

Now we'll initialise the local git clone and point it to the remote repo on the Odroid XU4.

$ pass git init
$ pass git remote add origin donquichote@odroidxu4:~/git/pass-store.git

After this, you can add passwords and directories at your leisure, the following command will e.g. add a password entry under Websites/work/:

$ pass insert -m Websites/work/someworksite

The author's suggestion for best practice (password on the first line, extra info on subsequent lines) is one I am following as well, and it's suited to the workflow Pass is intended for: clipboard functionality relies on the first line being your actual password.

Setting up further clients

There's a catch to having more than one client talk to your remote git repo. Since the remote repo already contains data, you'll need to pull that in first, with a regular git clone, before initialising your password vault. Git only wants to clone into an empty directory.

$ git clone donquichote@odroidxu4:~/git/pass-store.git ~/.password-store/
$ pass init "Don Quichote (Main key)"

If everything went well, you'll see the git log of your previous commits and also all the passwords pass now manages:

$ pass git log
$ pass

Make sure you import the same GPG key on each client, and have GPG mark it as trusted; otherwise, you won't be able to manipulate your passwords, and you'll be seeing messages like this:

There is no assurance this key belongs to the named user.

Synchronising your git repo

Pass will execute regular git commands if you append them, e.g. to push your newly added passwords, enter

$ pass git push

Similarly, if you want to update another client, do

$ pass git pull

OTP (One Time Password) tokens extension

Lots of websites offer 2FA as an added layer of security, often through OTP tokens (which you can generate with e.g. FreeOTP or AndOTP). With the Pass OTP extension, you can integrate OTP support into Pass as well. Installation (on Debian) and usage below. If you want to import QR codes, you'll also need to install zbar-tools, which provides zbarimg on Debian. I'll import my QR code for Amazon below, add it to my existing password entry for Amazon, and finally generate an OTP code.

$ sudo apt-get install pass-extension-otp zbar-tools
$ zbarimg -q --raw ~/amazon-otp.png | pass otp append Webshops/Amazon
$ pass otp Webshops/Amazon
12345A

Android client

I'm using Android Password Store, which relies on OpenKeychain to handle your GPG key. Make sure to import your private GPG key into OpenKeychain. Both apps are available through the Google Play Store and F-Droid, and are Free Software. The Password Store app allows you to use SSH keys to synchronise; to minimise possible exposure I'd recommend you use a key set that is limited to just the git sync through SSH's forced command functionality.