FOSS Password Management with passwordstore

Carlos Alexander Vializ
6 min readMay 18, 2016

There are many many sources about the dangers of password re-use. Even without re-use, passwords that are weak and memorable threaten account security. I too have previously succumbed to lazy password choices, but no more! After reading about passwordstore on HackerNews recently, I finally stopped putting it off and investigated a solution for secure, random, managed passwords.

This will be a small tutorial of sorts, because as I was setting up pass, I ran into some problems that turned up few results, so maybe my walkthrough will help someone with a similarly configured computer.

Create a key pair

The first step to using passwordstore (or pass for short) is installing its dependency gpg and using it to create a key pair.

Use your universal install script/favorite package manager to install gpg. Then run the following command.

$ gpg --gen-key

You’ll see a prompt:

gpg (GnuPG) 1.4.19; Copyright (C) 2015 Free Software Foundation, Inc.
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
Please select what kind of key you want:
(1) RSA and RSA (default)
(2) DSA and Elgamal
(3) DSA (sign only)
(4) RSA (sign only)
Your selection?

The default 1 is what you need. Then the next prompt:

RSA keys may be between 1024 and 4096 bits long.
What keysize do you want? (2048)

I chose 4096, because from my perspective the added security is worth the extra computation time to generate and en/decode.

Requested keysize is 4096 bits       
Please specify how long the key should be valid.
0 = key does not expire
<n> = key expires in n days
<n>w = key expires in n weeks
<n>m = key expires in n months
<n>y = key expires in n years

It’s trivial to extend the expiration date of your key, so again for safety and security I chose 1y here.

Key is valid for? (0) 1y
Key expires at Sat Apr 29 15:33:48 2017 PDT
Is this correct? (y/N) y

Next enter your identifying information. Later this is used to reference the key. You can use the key’s unique fingerprint if you have multiple keys with the same email address, but it’s less convenient to type out.

You need a user ID to identify your key; the software constructs the user ID
from the Real Name, Comment and Email Address in this form:
"Heinrich Heine (Der Dichter) <>"
Real name: Carlos
Email address:
You selected this USER-ID:
"Carlos <>"
Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? o

Simple enough.

You need a Passphrase to protect your secret key.

Choose a strong passphrase for the key. The key’s passphrase is like the Master Password in solutions like 1Password or KeePass. You’ll need it to decrypt the key and decode your password files. The key passphrase is your last line of defense. Choose something long, memorizable, and preferably truly random.

We need to generate a lot of random bytes. It is a good idea to perform some other action (type on the keyboard, move the mouse, utilize the disks) during the prime generation; this gives the random number generator a better chance to gain enough entropy.

gpg: key DEADB33F marked as ultimately trusted
public and secret key created and signed.
gpg: checking the trustdb
gpg: 3 marginal(s) needed, 1 complete(s) needed, PGP trust model
gpg: depth: 0 valid: 6 signed: 0 trust: 0-, 0q, 0n, 0m, 0f, 6u
gpg: next trustdb check due at 2017-04-28
pub 4096R/DEADB33F 2016-04-29 [expires: 2017-04-29]
Key fingerprint = 2233 4444 5677 7788 8999 AAAA ABBB CCCD DDEE EEFF
uid Carlos <>
sub 4096R/B33FF00D 2016-04-29 [expires: 2017-04-29]

You’re the proud owner of a new key pair!

Using fewer keystrokes

To prevent carpal tunnel, allow your computer to remember your password for a customizable amount of time: Install gpg-agent and configure it. You’ll want your gpg-agent.conf to look something like this.

# ~/.gnupg/gpg-agent.conf
# pinentry-program /usr/local/bin/pinentry-mac # if you're on OSX
pinentry-program /usr/local/bin/pinentry-curses

And you need to start gpg-agent when your terminal session starts so edit your ~/.bash_profile and then source it to .

# ~/.bash_profile
eval $(gpg-agent --daemon) # sets some environment variables

And then edit your ~/gpg.conf to use the agent daemon. There may already be a commented-out line for it, so you can just uncomment that line.

# ~/.gnupg/gpg.conf

Install and configure pass

Now comes the good part: using pass and generating some passwords. First we’ll install pass, then initialize it with our key pair’s id.

$ brew install pass # on OS X, more detail at
$ source /usr/local/etc/bash_completion.d/password-store
$ pass init
mkdir: created directory ‘/home/carlos/.password-store’
Password store initialized for

If you’re going to use pass on multiple devices, you’ll want to use its git functionality. I created a git repository for pass on Bitbucket, since you can create private repos for added privacy. Whichever git repository you use, add your ssh public keys (from ~/.ssh/ to your account so you don’t need a password to use your password repository.

$ pass git init
Initialized empty Git repository in /home/carlos/.password-store/.git/
$ pass git remote add origin
$ pass git push
Counting objects: 1, done.
Delta compression using up to 8 threads.
Compressing objects: 100% (1/1), done.
Writing objects: 100% (1/1), 8.55 KiB | 0 bytes/s, done.
Total 1 (delta 1), reused 0 (delta 0)
To git@user/pass.git
d3adb33..b4df00d master -> master

Information disclosure

Pass allows you to create folders for passwords. The folders can organize passwords by account to keep things neat, but any organization method you choose can work. The folders or files can be named directly after the service. Or if you don’t want to disclose which services you have accounts for, you can generate random keys that map to service names and store the mapping with pass too.

$ pass generate -c $(pwgen 8 1)/password 20
Copied aidei2OY/password to clipboard. Will clear in 45 seconds.
$ pass insert mapping --multiline # use "pass edit" in the future
Enter contents of test and press Ctrl+D when finished:


You’ll still want to log into your various accounts from your smartphone sans command line. On Android you can use the Android Password Store app in concert with OpenKeychain. On iOS there is an app available, but things are a little more locked-down so you’ll need to own a rooted device and compile the app from source. Since my main mobile device runs Android, I’ll only cover the Android features.

Since I’m somewhat new to asymmetric keys and gpg, the tricky part for me on Android was transferring my private key from my computer to my phone. You can use the following commands to export a password-protected, encrypted key that is secure to transfer between devices.

# from generate a strong random password
$ gpg --armor --gen-random 1 20
# encrypt key, use password above when asked
$ gpg --armor --export-secret-keys | \
gpg --armor --symmetric --output mykey.sec.asc

Transfer this key to your device (preferably not through the Internet) and decrypt it in OpenKeyChain, which will then offer to import it. Then you can select the key in Android Password Store, download the git repository and enter your master password to retrieve your data. Delete the encrypted transfer files when you’re done for added security.

Tips and Tricks

As you update your passwords across your web presence, you’ll discover a lot about how different organizations set password requirements. Some will silently truncate your password if you enter one that is too long. Some have a very particular mix of special characters they allow. Some inexplicably force a maximum of 8 or more characters (hinting that they store passwords in plaintext). Given industry standard password practices, namely hashing and salts, password length has little reason to be restricted.

Given these limitations, it’s a good idea to test your passwords after you set them to prevent any surprises when you need to log in next. Also given the insecure nature of some sites’ password storage schemes, enable two factor authentication whenever possible.

For added convenience there are also browser extensions available to integrate with pass. Check out for information regarding the various clients.

Further Reading

I created a Kifi library containing the helpful resources above and others that I found during my research into pass. You can find it at Hopefully it’ll be useful as you work more with passwordstore.



Carlos Alexander Vializ

Pilot, serial unicyclist, software engineer @kifi. Let’s go!