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:

As per the ebuild's messages 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 want to use the 2FA to allow root to login with a password don't forget to set the option to allow this in the config (as the default has changed in OpenSSH 7.1). Otherwise you will see an "Invalid verification code" even though it's not related to the Google Authenticator.

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 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.

Windows Phone
For Nokia Lumia handsets Authenticator from Microsoft or Authenticator by slugonamission can be use. Both has ability to scan QR codes. Author of the last state:

This [Authenticator by slugonamission]'' can be used for Google's two step verification system. When enrolling on Google's site, the account name and secret can be automatically captured by selecting either "iPhone" or "Android" while enrolling and scanning the shown QR Code.''