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 does not send information to Google's servers, it just uses Google's two-factor authentication protocol and (open source) code.
Google published a document how the two-factor authentication system works [1] 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.
Server 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 consists of installing and configuring the PAM module. This allows any PAM-aware program use two-factor authentication.
Keep a login session active during configuration of two-factor authentication and during the authentication verification process, otherwise you might lock out yourself out of the system.
Installation
Install google-authenticator:
root #
emerge --ask sys-auth/google-authenticator
Additional software
As per the ebuild's messages media-gfx/qrencode is used to generate QR codes, which makes transferring shared secrets easier. The installation of qrencode is optional, not mandatory for the setup.
root #
emerge --ask sys-auth/media-gfx/qrencode
Configuration
To enable two-factor authentication for the whole system, globally, add following line to the PAM configuration file.
auth required pam_google_authenticator.so
Rather than requiring multi-factor authentication every time, it is possible to make it optional for public places, unsafe networks, CCTV-covered areas, but fall back to using the regular password at home or when it's felt safe to do so.
auth sufficient pam_google_authenticator.so
It's also possible to enable two-factor authentication for specific programs by configuring them one at a time.
OpenSSH
Use following configuration to setup PAM and two-factor authentication for OpenSSH only:
# To disable tunneled clear text passwords, change to no here!
PasswordAuthentication no
# Change to no to disable s/key passwords
ChallengeResponseAuthentication yes
# Set this to 'yes' to enable PAM authentication, account processing,
# and session processing. If this is enabled, PAM authentication will
# be allowed through the ChallengeResponseAuthentication and
# PasswordAuthentication. Depending on your PAM configuration,
# PAM authentication via ChallengeResponseAuthentication may bypass
# the setting of "PermitRootLogin without-password".
# If you just want the PAM account and session checks to run without
# PAM authentication, then enable this but set PasswordAuthentication
# and ChallengeResponseAuthentication to 'no'.
UsePAM yes
To allow 2FA for the root user to login with a password, following options in the configuration need to be set. If not, an "Invalid verification code" will be displayed in the log:
#change the default if you want to re-allow that
#PermitRootLogin prohibit-password
PermitRootLogin yes
Finally enable two-factor authentication for OpenSSH only:
auth required pam_google_authenticator.so
auth include system-remote-login
account include system-remote-login
password include system-remote-login
session include system-remote-login
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.
user $
google-authenticator
Do you want authentication tokens to be time-based (y/n) y Warning: pasting the following URL into your browser exposes the OTP secret to Google: https://www.google.com/chart?chs=200x200&chld=M|0&cht=qr&chl=otpauth://totp/larry@gentoo%3Fsecret%3DZBURIWIVW5UQP4F5PYZ75LHTXU%26issuer%3Dgentoo Failed to use libqrencode to show QR code visually for scanning. Consider typing the OTP secret into your app manually. Your new secret key is: ZBURIWIVW5UQP4F5PYZ75LHTXU Enter code from app (-1 to skip): -1 Code confirmation skipped Your emergency scratch codes are: 26221962 22963189 57587651 88889973 75012523 Do you want me to update your "/home/larry/.google_authenticator" file? (y/n) y Do you want to disallow multiple uses of the same authentication token? This restricts you to one login about every 30s, but it increases your chances to notice or even prevent man-in-the-middle attacks (y/n) y By default, a new token is generated every 30 seconds by the mobile app. In order to compensate for possible time-skew between the client and the server, we allow an extra token before and after the current time. This allows for a time skew of up to 30 seconds between authentication server and client. If you experience problems with poor time synchronization, you can increase the window from its default size of 3 permitted codes (one previous code, the current code, the next code) to 17 permitted codes (the 8 previous codes, the current code, and the 8 next codes). This will permit for a time skew of up to 4 minutes between client and server. Do you want to do so? (y/n) n If the computer that you are logging into isn't hardened against brute-force login attempts, you can enable rate-limiting for the authentication module. By default, this limits attackers to no more than 3 login attempts every 30s. Do you want to enable rate-limiting? (y/n) y
The wizzard will ask 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 transferred 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 the users home directory that contains the shared secret, this file must be kept secure.
ZBURIWIVW5UQP4F5PYZ75LHTXU
" RATE_LIMIT 3 30
" DISALLOW_REUSE
" TOTP_AUTH
26221962
22963189
57587651
88889973
75012523
The generated .google_authenticator file has following, working default file permissions:
user $
ls -lah
-r-------- 1 larry larry 110 Jan 7 09:45 .google_authenticator
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.
Both application were tested with accounts at web sites such: GitHub, Facebook, Google, LastPass, Microsoft. All of them are working correctly
See also
- OATH-Toolkit — toolkit for (OTP) One-Time Password authentication using HOTP/TOTP algorithms.
- PAM — allows (third party) services to provide an authentication module for their service which can then be used on PAM enabled systems.
- PAM securetty — restricting root authentication with PAM.
- YubiKey — a hardware security device that can be used to safely store cryptographic keys, OTP tokens, and challenge response seeds
- Password management tools — This meta article is dedicated to secure password generation, auditing of generated passwords for security, and management of existing passwords.