Example PAM module demonstrating two-factor authentication.

Build and install by running "make install". If you don't have access to
"sudo", you have to manually become "root" prior to calling "make install".

Then add this line to your PAM configuration file:
  auth required pam_google_authenticator.so

Run the "google-authenticator" binary to create a new secret key in your home
directory.

If your system supports the "libqrencode" library, you will be shown a QRCode
that you can scan using the Android "Google Authenticator" application.

If your system does not have this library, you can either follow the URL that
"google-authenticator" outputs, or you have to manually enter the alphanumeric
secret key into the Android "Google Authenticator" application.

In either case, after you have added the key, click-and-hold until the context
menu shows. Then check that the key's verification value matches (this feature
might not be available in all builds of the Android application).

Each time you log into your system, you will now be prompted for your
TOTP code (timebased one-time-password) after having entered your normal user
id and your normal UNIX account password.

During the initial roll-out process, you might find that not all users have
created a secret key, yet. If you would still like them to be able to log
in, you can pass the "nullok" option on the module's command line:

  auth required pam_google_authenticator.so nullok

If you discover that your TOTP code never works, this is most commonly the
result of the clock on your server being different from the one on your Android
device. The PAM module makes an attempt to compensate for time skew. You can
teach it about the amount of skew that you are experiencing, by trying to log
it three times in a row. Make sure, you always wait 30s (but not longer), so
that you get three distinct TOTP codes.

Some administrators prefer that time skew isn't adjusted automatically, as
doing so results in a slightly less secure system configuration. If you want
to disable it, you can do so on the module command line:

  auth required pam_google_authenticator.so noskewadj

If your system encrypts home directories until after your users entered their
password, you either have to re-arrange the entries in the PAM configuration
file to decrypt the home directory prior to asking for the OTP code, or
you have to store the secret file in a non-standard location:

  auth required pam_google_authenticator.so secret=/var/unencrypted-home/${USER}/.google_authenticator

would be a possible choice. Make sure to set appropriate permissions. You also
have to tell your users to manually move their .google_authenticator file to
this location.

In addition to "${USER}", the "secret=" option also recognizes both "~" and
"${HOME}" as short-hands for the user's home directory.

When using the "secret=" option, you might want to also set the "user="
option. The latter forces the PAM module to switch to a dedicated hard-coded
user id prior to doing any file operations. When using the "user=" option, you
must not include "~" or "${HOME}" in the filename.

The "user=" option can also be useful if you want to authenticate users who do
not have traditional UNIX accounts on your system.

By default, the PAM module does not echo the verification code when it is
entered by the user. In some situations, the administrator might prefer a
different behavior. Pass the "echo_verification_code" option to the module
in order to enable echoing.

Some PAM clients cannot prompt the user for more than just the password. To
work around this problem, this PAM module supports stacking. If you pass the
"forward_pass" option, the "pam_google_authenticator" module queries the user
for both the system password and the verification code in a single prompt.
It then forwards the system password to the next PAM module, which will have
to be configured with the "use_first_pass" option.

In turn, "pam_google_authenticator" module also supports both the standard
"use_first_pass" and "try_first_pass" options. But most users would not need
to set those on the "pam_google_authenticator".

If you would like verification codes that are counter based instead of
timebased, use the "google-authenticator" binary to generate a secret key in
your home directory with the proper option.  In this mode, clock skew is
irrelevant and the window size option now applies to how many codes beyond the
current one that would be accepted, to reduce synchronization problems.