== Building and installing Google Authenticator ==

Note that this applies only to building the authenticator piece.  Information on installing and using the token generator is available [[http://www.google.com/support/accounts/bin/answer.py?hl=en&answer=1066447|here]], with the caveat that if you're not planning on using two-factor authentication with your Google accounts, just download the app.  Do NOT follow the instructions to configure your Google account.

The following applies to making Google Authenticator part of the two-factor authentication procedures on your Linux box.

Prerequisites:

* C compiler with standard libraries and headers
* libpam (might be libpam0g)
* libpam-dev (might be libpam0g-dev)
* libpam-modules
* libpam-runtime
* any application-specific pam modules that might be applicable, such as libpam-ssh
* mercurial (the distributed source code control system)
* optional but highly desirable: libqrencode3 and libqrencode-dev
* You should have the Google Authenticator smart phone app installed on your phone

Procedure:

1. Download source from code.google.com using the instructions at [[http://code.google.com/p/google-authenticator/source/checkout]]
2. cd into the google-authenticator/libpam directory
3. type "make"
4. run it locally to make sure that it built correct.  When it asks if you want to update your "~/.google_authenticator" file, type "n". Note that if you do not see a QR barcode on your screen, libqrencode-dev is not installed.  The interaction should look something like this:
[[Image(Screenshot-sxmls@google-authenticator.png)]]
5. If it looks healthy, get your secret key provisioned and available to your phone and to your Linux account.  I'm describing the process on an Android phone because that's what I've got.  (Someone may want to add instructions for iPhone or Blackberry):
 1.  run ./google-authenticator again
 1.  fire up Google Authenticator on your phone
 1.  if you're generating QR barcodes on the server, choose the phone's Google Authenticator menu item to scan the barcode.  Scan the barcode, and click when it notifies you that it found the URL.  When the server side google-authenticator asks if you want to update your ~/.google_authenticator file, type "y".  
 1.  if you're *not* generating QR barcodes on the server, you'll need to add the account manually based on the data printed out by the server's google-authenticator program
 1.  in either case you'll be asked some questions before google-authenticator updates your ~/.google_authenticator file.  
   1. The first question is whether or not you want to allow a given token value more than once.  If you say "y" you won't have to wait for the token value to turn over before authenticating again, but you risk an eavesdropper snagging the token and reusing it before the window closes.  The tokens roll over every 30 seconds, so on average you'll have to wait about 15 seconds for a new token if you say "n"
   1. The second question is about poor time synchronization between your phone and the server.  By default, they can be out of sync for up to 90 seconds and the authenticator will still work.  If you've got reason to think that your phone and the server might be out-of-sync by more than 90 seconds, answering "y" here increases the tolerable time skew to 4 minutes.
   1. The last question is whether or not you'd like to limit login attempts to 3 every 30 seconds.  This is to protect against brute-force attacks, in which the attacker tries every value in the space until it gets a match.  Since there are only 1,000,000 possible codes, on average one can be found in only 500,000 guesses.  Since guessing involves absolutely no computation to speak of (integer increment by one is a machine instruction), it's a very good idea to enable rate-limiting here.
 1. now, verify that it's actually working by running the demo program in the source directory.  When it asks for your Verification code:, type in the six-digit number provided by the Google Authenticator app on your phone.  If it's successful it says nothing and returns you to the prompt.  If it's not successful it prints "Login failed  Invalid verification code"
6. If it still looks healthy, with root privileges type "make install".  This will install the pam module in /lib/security and the "google-authenticator" executable in /usr/local/bin.
7. You're now ready to configure pam to use Google authenticator as a second auth factor (never, '''ever''' use it as a single authentication mechanism).  This is currently a per-machine mechanism, which means that you'll need to install and configure it on each machine for which you'd like to use it, and users will need to run google-authenticator to initialize and provision keys on each machine.