Google Authenticator

This article describes an easy way to setup two-factor authentication on Gentoo. The google-authenticator project provides mobile applications and a PAM module that make this possible. Setting up two-factor authentication using Google Authenticator requires a supported mobile device. Currently Android, iOS and Blackberry are supported. Note that this authentication method doesn't talk to Google's servers, it just uses Google's two-factor authentication protocol and (open source) code.

Google has a pretty good video description of how their two-factor authentication system works for their web-based systems. Using the code provided by the google-authenticator project it's possible to setup the same authentication method for your own systems.

Host Setup
The google-authenticator project comes with a PAM module that allows any PAM-aware program to support two-factor authentication. The host-side setup of consists of installing and configuring the PAM module. This allows any PAM-aware program use two-factor authentication.

Installation
The easiest way to install is probably to just use the ebuild. It's not in portage yet, so you'll want to add the "sunrise" overlay. At which point the ebuild should work:

As per the ebuild's messages "media-gfx/qrencode" is used to generate QR codes, which make transferring shared secrets significantly easier.

Be sure to keep a login active between configuring two-factor authentication and verifying that it works, otherwise you could find yourself locked out of your system!

Configuration
It's possible to globally enable two-factor authentication by adding the following line to your global PAM configuration. Note that this means every login to your system will require two-factor authentication (even sudo!) so it's very important to have a login persist until you have a mobile device with a shared secret setup.

It's also possible to enable two-factor authentication for specific programs by configuring them one at a time.

OpenSSH
There is a bit of additional configuration required to enable PAM and two-factor authentication in OpenSSH. These settings seem to work well

If you didn't setup global two-factor authentication globally then you'll want to enable it for OpenSSH.

Secret Generation
The easiest way to distribute secrets to client machines is by scanning QR codes. If you're planning on using a QR code you'll have to have a terminal window that is at least 85 characters wide otherwise the QR code will be unreadable and you'll need to generate another code (or deal with editing the ASCII art). Once you've resized your terminal window properly you can generate a key by logging in to the host and running the key generation wizard.

This will ask a few questions and generate an ASCII art QR code. Keep this QR code visible and continue with setting up your client. This QR code contains the shared secret that will be transfered to your client device, so it's important to keep this safe. The QR code will only be used once, so I recommend just keeping it in your terminal's buffer.

You can generate a new secret at any time, so it's not necessary to backup this secret (in fact, that somewhat defeats the point). By default the wizard will create a file called ".google_authenticator" in your home directory that contains the shared secret, this file must be kept secure.

Client Setup
The client-side setup is specific to the device you'll be using to store the shared secret. The google-authenticator project provides client programs for Android, iOS, and Blackberry.

Android
The Android google-authenticator code can be installed from the android market by searching for "Google Authenticator". After it's installed you can scan the QR code (Menu -> Add Account -> Scan Barcode) generated above which will transfer the secret to your Android phone.