Set of scripts to manage google-auth setup on Gentoo Infra
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.


Google Authenticator (PAM) wrappers

Ⓒ 2018 Michał Górny

Licensed under the terms of 2-clause BSD license


This package provides a few wrappers for the purpose of using Google Authenticator PAM modules [1] for two-step SSH authentication securely. It is specifically focused on the use in Gentoo Infrastructure [2] but can be used on any multi-user system. It satisfies the following goals:

  1. HOTP/TOTP is used as second step, combined with SSH pubkey authentication.
  2. Two-step authentication is entirely optional. Users who did not enable it use regular pubkey-only authentication.
  3. Secrets (and emergency scratch codes) are not readable to user, and can only be modified (and second step can only be disabled) after password authentication.

Problems with google-authenticator-libpam

The standard configuration of google-authenticator-libpam relies on storing secrets in user's home directories. While this is convenient to users, it raises security-related concerns. For example, if an attacker manages to temporarily gain access to the user's session or the filesystem, he can easily read the secrets and duplicate the token source without leaving much of a trace that the system has been compromised.

For comparison, shadow passwords are not readable to the user (even though they are normally hashed). The user also can't change his password without typing the old password first. SSH authorized_keys are usually not protected but we still can assume that the attacker would not have enough resources to recreate the private key material from the public key.

This problem could be solved via storing keys separately, and making them unreadable to user. However, this implies that either the sysadmin needs to manually update user's secrets or there needs to be additional automation doing that. Those wrappers aim to be the latter.


This package includes a standard CMake-based build system with GNUInstallDirs support. The following additional configuration variables are provided:

Directory where pam.d files should be installed (/etc/pam.d).
Directory where user secrets will be stored (/var/lib/gauth).
User used to manage secrets (root).

Please note that the install target does not take care of changing file ownerships or modifying configuration of live services. You need to update your /etc/pam.d/ssh and OpenSSH or similar setup manually.

You also need to make sure that gauthctl and gauth-test are both owned by GAUTH_USERNAME and setuid. The statedir needs to also be owned by GAUTH_USERNAME, and kept unreadable to other users.


The following executables are intended for user's direct use:

Disables second step authentication for the current user.
Enables second step authentication with full google-authenticator prompt set.
Enables second step authentication with Gentoo TOTP defaults.
Performs a test second step authentication. Used to verify that the current setup is working correctly.

Implementation details

The three wrapper scripts use gauthctl to update the user secrets. This tool takes a single option, --enable or --disable appropriately, performs PAM authentication (using standard system mechanism, i.e. the regular user password) and updates the secret.

The --enable option reads new configuration from fd 3, and writes it to the isolated secret directory after successful PAM authentication. The --disable option simply removes the secret, effectively disabling the second step authentication.


[1]Google Authenticator PAM module (
[2] 2-step authentication (