Home

Awesome

pam-gnupg

Unlock GnuPG keys on login

What is it?

A PAM module that hands over your login password to gpg-agent, which can be useful if you are using a GnuPG-based password manager like pass.

Requires GnuPG 2.1, and probably only works on Linux.

Disclaimer

The code was written mainly by looking at and occasionally copying from Gnome Keyring's PAM module and pam_mount and is based on a somewhat mediocre understanding of the details of both PAM and C. You should be aware that there may be potentially dangerous bugs lurking.

Installation

Packages

Manually

The usual

./autogen.sh
./configure
make
make install

should work. configure takes an option --with-moduledir to set the installation path of the PAM module. It defaults to /lib/security, but your distribution might use a different path.

Usage

Setup guide

GNUPGHOME

If you change your gnupg directory from the default ~/.gnupg by setting GNUPGHOME, this variable needs to be made available to pam-gnupg when presetting. Since PAM usually runs before your init scripts, it needs to obtain the variable in a different way.

To set it, add the path to the config file on a separate line before any keygrips, either as absolute path or starting with ~/ for paths relative to the home directory. The connection to the agent will be opened when the first keygrip is read, so setting GNUPGHOME after that will have no effect.

Note that the variable is only used for connecting to and optionally autostarting the agent. It is not passed down to your login shell or desktop session, so you also need to set it in your init scripts. Additionally, if you start the agent via systemd, you need to adjust the various service and socket units separately.

Alternatives

If you use systemd-homed, you can modify env vars via homectl --setenv, and they will be made available to PAM by pam_systemd_home.so.

Another way is to run pam_env.so with user_readenv=1 before pam_gnupg.so, so you can set env vars from ~/.pam_environment, e.g.

GNUPGHOME DEFAULT=@{HOME}/path/to/your/gnupg

You can also modify XDG_CONFIG_HOME this way. Unfortunately, user_readenv is deprecated and will go away in some future version of pam_env.

SSH Keys

SSH key support is indirect via gpg-agent's built-in SSH support (there's no SSH specific code in pam-gnupg). The full details are in gpg-agent(1), but here's a basic step-by-step guide:

Debug output

Both the auth and the session module take a debug option to enable some basic debug logging to syslog / journal.

Known issues

Contact