Tricks of the Trades

Pass Unix Password Manager

GPG Lock

Preamble

Pass is a command line password manager that follows the Unix philosopy of being small, simple, efficient, and compatible. It works by storing machine generated or user generated passwords in an encrypted GPG file. Each of which are organised into a named folder hierarchy. It can be manipulated through other command line tools if needed, and its contents easily transferred from system to system.

As indicated Pass operates with traditional command line options and arguments, and has commands for adding, editing, generating, and retrieving specific passwords. It also has built in features such as the ability to temporarily load passwords onto your system clipboard, and track password changes using version control such as Git.

All passwords expand from a root folder created with the path; ~/.password-store and the hierarchy of descending passwords expands from there. You can if preferred interact with the password store using other ordinary Linux/Unix shell commands instead. Furthermore there’s provided Bash completion so that you can hit TAB to fill in paths and file names (Zsh completion is also available).


Step 1 – Create A GPG Key

To begin using Pass you first need a GPG key.

You can create one by issuing the following command in a Linux Bash terminal on most distributions:

1
$ gpg --gen-key

Note: On Arch Linux Install GPG first with: sudo pacman -S gpg

The initial prompt will appear and looks like this:

1
2
3
4
5
6
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?

Choose 1 which will enable both encryption and signing.

The next prompt asks for the keysize:

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

Enter 2048 for the keysize.

Then read the next set of output:

1
2
3
4
5
6
7
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
Key is valid for? (0)

Most people make their keys valid until infinity, which is the default option. If you do this don’t forget to revoke the key when you no longer use it.

Enter 0 for infinity, or however long you wish.

1
2
3
You need a user ID to identify your key; the software constructs the user ID
from the Real Name, Comment and E-mail Address in this form:
"Heinrich Heine (Der Dichter) <heinrichh@duesseldorf.de>"

Your next input from here should be your real name:

1
Real name:

Followed by your email address you wish to associate the key with (you can add more later!) :

1
E-mail address:

Here you can give the key a description that fits its purpose:

1
Comment:

This part is important and is the passphrase that you’ll use to open/decrypt your key that is generated. You can make it memorable but it’s essential that this follows a few precepts to make it strong and considered “secure”.

For Example: Contains symbols, contains upper & lower case characters, some numbers, no dictionary words, etc.

1
2
3
You need a Passphrase to protect your secret key.

Enter passphrase:

As the next prompt says type on the keyboard, move the mouse, and perform some actions that read/write to the machine’s hard drives.

1
2
3
4
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, use the
disks) during the prime generation; this gives the random number
generator a better chance to gain enough entropy.

If this is not enough or does not seem to update and complete after sometime, open up a new shell session and carry out these commands:

1
2
$ sudo apt-get install rng-tools
$ sudo rngd -r /dev/urandom

The process should now continue and include your new key’s location, value, and details.

With the main line reading:

1
public and secret key created and signed.

One more step you can complete locally is to set your key as the default key by entering this line in your ~/.bashrc file:

1
$ export GPGKEY=<key value>

Now restart the gpg-agent with:

1
2
$ killall -q gpg-agent
$ eval $(gpg-agent --daemon)

Then source your .bashrc again via:

1
$ source ~/.bashrc

Step 2 – Creating A Revocation Certificate

A revocation certificate must be generated to revoke your public key if your private key becomes compromised in any way.

It is recommended to create a revocation certificate when you create your key.

Note: Keep your revocation certificate on a medium that you can safely secure, like a thumb drive in a locked box. The revocation key may be printed and/or stored as a file. Take care to safeguard your revocation key.

To create a revocation certificate for your key carry out these two commands.

This first statement will create an environment variable in Bash containing the GPG key value you just created. Note that if you have other keys previously generated the value extracted with this command may be of a different key, this filters on the first key listed by the gpg program:

1
$ export GPGKEY="$(gpg -K | awk 'NR==3 {print $2}' | sed 's/2048R\///g')"

Now we create the revocation certificate by passing the $GPGKEY variable we defined:

1
$ gpg --output revoke.asc --gen-revoke $GPGKEY

Enter 0 for this multiple choice list.

1
2
3
4
5
6
7
8
Create a revocation certificate for this key? (y/N) y
Please select the reason for the revocation:
0 = No reason specified
1 = Key has been compromised
2 = Key is superseded
3 = Key is no longer used
Q = Cancel
(Probably you want to select 1 here)

Enter something along the lines of - “Will be used if/when this key is ever compromised.”

This also needs ending with a new line.

1
2
3
Enter an optional description; end it with an empty line:
>
>

Now enter your key’s passphrase

1
2
You need a passphrase to unlock the secret key for
user:

The resultant message seen here means you successfully created your revocation certificate.

1
2
3
4
5
6
7
8
ASCII armoured output forced.
Revocation certificate created.

Please move it to a medium which you can hide away; if Mallory gets
access to this certificate he can use it to make your key unusable.
It is smart to print this certificate and store it away, just in case
your media become unreadable. But have some caution: The print system of
your machine might store the data and make it available to others!

Note: Mallory being a malicious attacker (less commonly called Trudy, an intruder.); unlike the passive Eve, this one is the active man-in-the-middle attacker who can modify messages, substitute his/her own messages, replay old messages, and so on. – Source

As indicated backup somewhere safe the revoke.asc file, in case you should ever need it in the future to invalidate your private key.

It can be found in your current working directory where you executed the initial gpg --output command.


Step 3 – Installing Pass

Arch Linux

1
$ sudo pacman -S pass

Debian / Ubuntu

1
$ sudo apt-get install pass

Step 4 – Initialising Pass

After installing Pass you need to initialise it with your GPG key from the previous steps.

In the same shell session as earlier use the environment variable $GPGKEY and supply it to Pass via the init parameter:

1
$ pass init $GPGKEY

This message will follow:

1
2
mkdir: created directory ‘/home/scarlz/.password-store’
Password store initialized for <KEYVALUE>.

Step 5 – Adding Password Entries

To add a new password entry to Pass, follow this next code snippet’s syntax:

1
$ pass insert email/proton-mail/count.elmsley@protonmail.com

This example was for an entry of an email address account in a descriptive hierarchy.

The prompt generated asks for the password that is to be associated and stored with this entry

1
2
3
4
mkdir: created directory ‘/home/scarlz/.password-store/email’
mkdir: created directory ‘/home/scarlz/.password-store/email/gmail’
Enter password for email/proton-mail/count.elmsley@protonmail.com:
Retype password for email/proton-mail/count.elmsley@protonmail.com:

The password is then read encrypted, and placed in ~/.password-store .

As the data stored in the encrypted files are plain text you can add any other details that go with an entry using the -m parameter. This creates the password with a multi-line entry where the first field is usually the password and the rest of the lines are the extra details such as usernames, emails addresses, etc.

1
$ pass insert -m email/proton-mail/count.elmsley@protonmail.com

Press CTRL + D to quit and confirm the entry when in multi-line mode.

To use Pass to generate a password for an entry on your behalf, use the generate option:

1
$ pass generate archlinux.org/wiki/username <n>

The <n> represents the number of characters you want the password to be in total. Replace it with a value like 16 to make the password lengthy enough.

There are some other options you can toggle like -n to exclude symbols from the password, and -c to send the password straight to the clipboard, and not print it to standard out once it’s created.

1
$ pass generate -n -c archlinux.org/wiki/username 16

Step 6 – Displaying & Accessing Passwords

The most basic and easiest way of displaying your password hierarchy tree is by running the program without any extra options:

1
$ pass
1
2
3
4
5
6
7
8
9
10
11
Password Store
├── Business
│ ├── some-silly-business-site.com
│ └── another-business-site.net
├── Email
│ ├── user@gmail.com
│ └── zx2c4.com
└── France
├── banking
├── freebox
└── mobilephone

If you want to single out certain categories or sections of the tree use:

1
$ pass ls Email/

Which shows only:

1
2
3
├── Email
│ ├── user@gmail.com
│ └── zx2c4.com

To actually decrypt and retrieve a password, call the program and provide the path to the password:

1
$ pass Email/user@gmail.com

You will now have to enter or unlock your GPG key to see and display the password.

Instead of displaying the password in the terminal you can copy it to the clipboard for 45 seconds via -c :

1
$ pass -c Email/user@gmail.com

Which gives the message below and let’s you paste the password into any websites, forms, etc:

1
Copied Email/user@gmail.com to clipboard. Will clear in 45 seconds.

Step 7 – Removing & Editing Password Entries

You many need to remove passwords in the manager from time to time. This is done with the familiarly named rm and the path to the password file you want to remove.

Here an example:

1
$ pass rm email/proton-mail/count.elmsley@protonmail.com

To remove the folders in the process of the deletion include -r (recursively) in the command:

1
$ pass rm -r email/proton-mail/count.elmsley@protonmail.com

Normally there is a prompt to make sure you are certain you want to delete the password, this can be removed by using -f which is short for ‘force” :

1
$ pass rm -f email/proton-mail/count.elmsley@protonmail.com

To change an existing password and edit it replace rm with edit like this:

1
$ pass edit email/proton-mail/count.elmsley@protonmail.com

Step 8 – Git Version Control

Pass has support for Git tracking which would be ideal for private Git repositories but also in theory “safe” to put on a public service like Github, as the files are of course encrypted with GPG. Depending upon the strength of your passphrase too.

Make sure you have git installed on your system for this next section:

Arch Linux

1
$ sudo pacman -S git

Debian / Ubuntu

1
$ sudo apt-get install git

Here’s how the Git functionality works with pass:

1
$ cd /$USER/.password-store

Initialise the repository through pass:

1
$ pass git init

Add your remote repo address and name:

1
$ pass git remote add origin git-repo-address.com:repo-name

Set Git to push with these options:

1
$ pass git push -u --all

You can now add, edit, remove, and make changes then push them to your remote repository with:

1
$ pass git push

Step 9 – Shell Environment Variables

Here are three variables I found that seem potentially the most useful, should you ever need to fiddle with their functionality (there are others though).

PASSWORD_STORE_DIR
Overrides the default password storage directory.

$PASSWORD_STORE_GIT
Overrides the default root of the git repository, which is helpful if PASSWORD_STORE_DIR is temporarily set to a sub-directory of the default password store.

$PASSWORD_STORE_CLIP_TIME
Specifies the number of seconds to wait before restoring the clipboard, by default 45 seconds.


Step 10 – Exporting & Importing Keys

To transfer and move around a pass GPG key to other systems, follow these steps for a rudimentary solution.

Public Key

To see the current public GPG keys you have setup and active use:

1
$ gpg --list-keys

One of these will show the ID and details of your Pass key, use the key ID value to export the public key into a file with:

1
$ gpg -ao pass_public.key --export <key ID value>

Then transfer the generated pass_public.key onto your new system, and use the --import option to add it to GPG.

This is done with the command:

1
$ gpg --import pass_public.key

Private Key

To see the current private GPG keys you have setup and active use:

1
$ gpg --list-secret-keys

Like in the public key section, export the private key into a file with:

1
$ gpg -ao pass_private.key --export-secret-keys

Then transfer the generated pass_private.key onto your new system, and use the --import option to add it to GPG.

This is done with the command:

1
$ gpg --import pass_private.key

Trust Error

Sometimes after importing the key onto a new system you may get an error message similiar to:

1
gpg: There is no assurance this key belongs to the named user

Which appers when trying to encrypt a new file or edit an existing Pass entry.

If so use GPG to edit the key.

1
$ gpg --edit-key <Key Value>

At the prompt type:

1
> trust

Then from the numerical choices displayed enter a suitable value. The highest option 5 is fine if you know that this key is definetly your own and not a potentially unsafe key.

1
2
3
4
5
6
7
8
9
10
11
Please decide how far you trust this user to correctly verify other users' keys
(by looking at passports, checking fingerprints from different sources, etc.)

1 = I don't know or won't say
2 = I do NOT trust
3 = I trust marginally
4 = I trust fully
5 = I trust ultimately
m = back to the main menu

Your decision?

The operation you were trying to perform with Pass should now work as they key is trusted. Enter quit to leave the gpg prompt.


On a final note the community around Pass has produced a cross-platform GUI client, an Android app, an iOS app, a Firefox plugin, a Windows client, a dmenu script, OS X integration, and even an emacs package.

So look into these if they sound interesting:

Pass on Github


More Information

Easily deploy an SSD cloud server on Digital Ocean in 55 seconds. Sign up using my link and receive $10.00 in free credit: https://www.digitalocean.com/?refcode=e91058dbfc7b

– Scarlz: @5car1z