From befadb9c31cd1e8a72484943e2f77af1f21f311e Mon Sep 17 00:00:00 2001 From: Michael Balsillie Date: Wed, 19 Aug 2026 13:45:55 -0400 Subject: [PATCH] Pass setup content --- docs/setup_pass.md | 109 ++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 103 insertions(+), 6 deletions(-) diff --git a/docs/setup_pass.md b/docs/setup_pass.md index 0e4f158..9773811 100644 --- a/docs/setup_pass.md +++ b/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 -chmod 700 ~/.config/gnupg +mkdir -p ~/.config/gnupg ~/.config/pass +chmod 700 ~/.config/gnupg ~/.config/pass ``` -Add the following line to `~/.bashrc` : +Add the following lines to `~/.bashrc` : ``` -GNUPGHOME=~/.config/gnupg +export GNUPGHOME=/home//.config/gnupg +export PASSWORD_STORE_DIR=/home//.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 +sub cv25519 2026-08-19 [E] +``` + +Initialize pass + +``` +pass init +``` + +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.