# How to setup Pass password utility

## Overview

Pass relies on gpg to encrypt the password store.
Thereofre this process is in two parts:
  - Setting up/initializing gpg
  - Setting up/initializing pass

## Prerequisites

Install required packages

```
sudo pacman -S gnupg pass
```

## Config directories and env vars

Both gnupg and pass will try to create folders in the root of your home directory.
This is untidy and should instead use the user's .config directory, which is intended for this purpose.
Fortunately, both pass and gnupg have environment variables to override this behavior.

Pre-stage the config dirs and lock down their permissions:

```
mkdir -p ~/.config/gnupg ~/.config/pass
chmod 700 ~/.config/gnupg ~/.config/pass
```

Add the following lines to `~/.bashrc` :

```
export GNUPGHOME=/home/<USER>/.config/gnupg
export PASSWORD_STORE_DIR=/home/<USER>/.config/pass
export GPG_TTY=$(tty)
```

The first two lines override the config directory locations for gnupg and pass.
The third line allows the gpg agent to correctly identify the current tty,
which is needed when launching the pinentry program for password input.

Also add the following alias line, which will be used to quickly unlock the password store in the future.

```
alias unlock='pass show unlock'
```

Then source .bashrc to load the new environment variables and alias

```
source ~/.bashrc
```

## GnuPG

By default, if you are using a graphical desktop, pinentry (password entry) will launch an interactive
window when prompting for passwords, which can be disruptive and annoying when working from the terminal.
Edit the gpg-agent config file at `~/.config/gnupg/gpg-agent.conf` to set the pinentry program, add the 
following line:

```
pinentry-program /usr/bin/pinentry-curses
```

Reload the gpg-agent for the config change to take effect.

```
gpg-connect-agent reloadagent /bye
```

Now we will create a gpg key pair, which will be used by pass to encrypt and decrypt the password store.

Generate a new GPG key pair

```
gpg --full-gen-key
```

Select the following options when prompted:

  - ECC (sign and encrypt)
  - Curve 25519
  - 0, key does not expire
  - Enter your real name
  - Enter an email address
  - Leave comment field blank
  - Type a password when prompted

The password you choose for the gpg key is what you'll need to unlock entries using pass

GPG should now be initialized, proceed to the next section to setup pass

## Pass

Run `gpg --list-keys` to display the key id of the gpg key generated in the previous section
Copy the key id to use with pass

```
$ gpg --list-keys
gpg: checking the trustdb
gpg: marginals needed: 3  completes needed: 1  trust model: pgp
gpg: depth: 0  valid:   1  signed:   0  trust: 0-, 0q, 0n, 0m, 0f, 1u
/home/michael/.config/gnupg/pubring.kbx
---------------------------------------
pub   ed25519 2026-08-19 [SC]
      D851CB6A289F9033C8B091FBF83E17CE5224E2B9  <<< THIS IS THE KEY ID 
uid           [ultimate] Michael Balsillie <michael@balsillie.net>
sub   cv25519 2026-08-19 [E]
```

Initialize pass

```
pass init <KEY ID>
```

Add the unlock entry

```
echo Unlocked | pass insert -e unlock
```

Running `unlock` should now prompt you for the password store password (your gpg key password) and display the `Unlocked` response.
Because gpg-agent keeps a key unlocked for a period of time, you can view multiple pass entries after unlocking once.