Pass setup content

docs/setup_pass.md

@@ -1,28 +1,125 @@
 # 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
 ```
 
-Create a config directory for GnuPG 
+## 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 ~/.config/gnupg
+mkdir -p ~/.config/gnupg ~/.config/pass
-chmod 700 ~/.config/gnupg
+chmod 700 ~/.config/gnupg ~/.config/pass
 ```
 
-Add the following line to `~/.bashrc` :
+Add the following lines to `~/.bashrc` :
 
 ```
-GNUPGHOME=~/.config/gnupg
+export GNUPGHOME=/home/<USER>/.config/gnupg
+export PASSWORD_STORE_DIR=/home/<USER>/.config/pass
+export GPG_TTY=$(tty)
 ```
 
-Then source .bashrc to add the new ENV var
+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.