FastLizard4.org Shell Server Two-Factor Authentication

Two-factor auth in use

This is not to be confused with two-factor authentication here on LizardWiki. For that, please see Special:TwoFactorAuth.

FastLizard4.org shell servers support two-factor authentication per the OATH-HOTP standard, specifically through the Google Authenticator PAM module. It is not enabled for any accounts by default, however, it is highly recommend that it be enabled regardless of whether you use passwords or keys to authenticate to SSH. Any application capable of generating OATH-HOTP tokens may be used with FastLizard4.org shell server two-factor auth, but the recommended method of generating tokens is with the Google Authenticator app, available for iOS, Android, and Blackberry devices. This page explains how to set up and use two-factor authentication on the FastLizard4.org shell servers.

Protected services

The following services are configured to be protected by two-factor authentication:

• login - Interactive logins from a serial console (probably won't concern you)
• ppp - PPP tunnelling, specifically LizardVPN - you MUST have two-factor authentication enabled and you MUST use it to use this service!
• sshd - Password-interactive logins over SSH
• su - The su command, aka Substitue User

If you set up two-factor authentication, only the services above will require you to use it. Notable services not in this list are imap and smtp (meaning that two-factor auth doesn't change the way you check your email on fastlizard4.org using an email client like Thunderbird), and passwd (meaning that you don't need to use two-factor authentication codes when changing your password; this is because of how easy it is to disable the system after you've logged in; sudo is not protected for similar reasons).

A note for those using SSH keys

If you use SSH keys to log in to the server, you won't be asked for your one-time passcode when logging in, and your key will log you in directly as before. This is for two reasons:

1. (technical) OpenSSH doesn't consult PAM if you're using pubkey authentication.
2. (practical) Key-based authentication is extremely secure, and making you enter your one-time token every time you auth by pubkey just adds time to what it takes for login, and also defeats the "automatic login" functionality of key-based authentication.

That said, it is still recommend that you set up two-factor auth, even if you use key-based authentication to log in by SSH, because of the security benefits it provides:

• Since your account still has a password associated with it, it makes it much, much, much more difficult for a hacker to "get around" your key by cracking your password.

Setting up two-factor auth

Setting up two-factor authentication is a fairly easy process, actually.

1. First, install whatever app or software you are going to use to generate your authentication tokens, and prepare it to add a new token. This application or software will be referred to "authenticator app" for the rest of the page.
2. Log in to the server as you normally would. Once you are at your shell prompt, enter the following command and press enter:

   google-authenticator

3. You will then see this:

   Do you want authentication tokens to be time-based (y/n) 

   If you answer "y" to this prompt, your authentication tokens will be time-based and refresh every thirty seconds; make sure you select "Time Based" for the token type in your authenticator app. If you answer "n", they will be counter based, meaning that you will manually refresh it every time you need one; make sure you select "Counter Based" for the token type in your authenticator app.

   Note: It is recommended that you choose time-based instead of counter-based. There appear to be some bugs related to counter-based tokens in the PAM module, specifically that the server-side counter gets incremented on failed login attempts as well as good ones. Otherwise, they work fine.

4. You will then be given a page with a QR code, the secret key, a verification code, and five emergency scratch tokens, (see screenshot here).

   This is where you need to enter your token details into your authenticator app. In Google Authenticator (and many other apps), simply scan the QR code shown (or the one provided by the "google.com/chart" link above it). If it doesn't work, enter your account name as "username@server" and your secret key as shown.

   The QR code seems to work in almost all cases, except for some reason if you're using a counter-based code; in this case, you'll probably need to enter your secret key into your authenticator app manually.

   Before continuing, write down or copy/paste the five emergency scratch codes in a secure and safe location. If you lose your device, these five emergency emergency scratch codes will be your ONLY way to log in and disable/reset two-factor authentication!! Likewise, make sure that no one else can find them, as they will effectively allow an attacker to bypass two-factor auth for your account.

5. You will then see the prompt:

   Do you want me to update your "/home/<username>/.google_authenticator" file (y/n) 

   If you are satisfied with your two-factor auth tokens, enter "y" and press enter to enable two-factor authentication protection. Authentication tokens will be required from now on for all protected services. If you changed your mind and don't want to enable two-factor auth, enter "n" and press enter. If you do abort, you can always start over should you re-change your mind.

   If you have already enabled two-factor auth and are rerunning the setup process to reset your scratch tokens and secret key, answering "y" to this prompt will commit your new key, and answering "n" will keep your old one.

6. If you answered yes to the above prompt, you will now be prompted for various options related to the two-factor authentication system. They will be different depending on whether you selected time-based or counter-based tokens, so go to the appropriate section to continue.

Time-based tokens

• The next prompt you will see is:

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) 

This should be self-explanatory. Answering "y" is more secure, but sacrifices some convenience for security. Answering "y" is also recommended, but you may answer "n" if you wish.

• Next:

By default, tokens are good for 30 seconds and 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. If you experience problems with poor
time synchronization, you can increase the window from its default
size of 1:30min to about 4min. Do you want to do so (y/n)

The server automatically synchronizes to UTC time, so it will always be "accurate". 1 minute 30 seconds should be fine, so you can probably answer "n" to this prompt, but if your device frequently has an inaccurate block, answering "y" is probably a good idea. Note that answering "y" does slightly decrease the security of the system.

• Finally:

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)

The server is hardened against brute-force attacks, but for some reason, authentication code failures don't log as password failures. For that reason, it is recommended that you answer "y" this prompt unless you have a reason for answering "n".

That's it! Congratulations, you're all set up to use two-factor auth! But please continue reading, as there are some things you still should know.

Counter-based tokens

• The next prompt you'll see is:

By default, three tokens are valid at any one time.  This accounts for
generated-but-not-used tokens and failed login attempts. In order to
decrease the likelihood of synchronization problems, this window can be
increased from its default size of 3 to 17. Do you want to do so (y/n)

It is recommended that you actually answer "y" to this prompt for the reasons mentioned here. Answering "n" is a bit too restrictive, and greatly increases the chance of you locking yourself out due to aforementioned synchronization problems, negating any security benefit (after all, is security worth it if it outright prevents you from logging in?).

• Finally:

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)

The server is hardened against brute-force attacks, but for some reason, authentication code failures don't log as password failures. For that reason, it is recommended that you answer "y" this prompt unless you have a reason for answering "n".

That's it! Congratulations, you're all set up to use two-factor auth! But please continue reading, as there are some things you still should know.

Using two-factor authentication

Once you've enabled two-factor authentication, using any of the services listed in the protected services list will prompt you for your password, and if you get it right, your verification code too. Your verification code should be gotten from your authenticator app. Note that if you time-based tokens and you answered "y" to the question about "Do you want to disallow multiple uses of the same authentication token", you may not use the same token more than once; wait for new tokens to be generated. If you use counter-based tokens, you'll need to press the button in your app to generate a new token every time you are prompted for one.

The prompt for your one-time token is like the one shown here.

Note that, as mentioned towards the top of the page, you will not be prompted for a one-time token if you use keys to log in by SSH. You will still be prompted for tokens, though, if you try to access any of the other protected services.

Help! I've locked myself out!

If you are finding that none of your tokens work, or if you lost your device with your authenticator app on it, it's time to break out those five emergency scratch tokens! Hopefully, you wrote them down somewhere back when you set up two factor authentication; just get the list, and type in one of the codes in place of a code you'd normally get from your authenticator app. Note that each code is only usable once, so once you've used one of them, scratch it off the list as it will never be usable again.

If you run out of scratch tokens, you'll have to reset two-factor authentication to get new ones. See below.

If you've somehow also lost your emergency scratch tokens, shame on you. After you feel sufficiently ashamed, contact a system administrator. The administrator will ask you to prove your identity, and if you do so sufficiently, they will disable two-factor authentication for your account. You may then log in and re-enable two-factor auth if you so choose.

Note: You can always look at the file .google_authenticator to see your secret key and available scratch tokens again. Don't worry; only you can see this file.

Disabling or resetting two-factor authentication

Disabling two-factor authentiation is easy enough. Simply log in to the server as you normally would, and in your home directory, delete or rename the file .google_authenticator. Moving it allows you to re-enable the system by moving the file back to .google_authenticator; either way, you won't be prompted for one-time tokens again until you re-enable the system one way or the other.

To reset your two factor authentication system (e.g., to generate a new secret key or a new set of emergency scratch tokens), simply perform the two-factor auth setup process again. Note that even if you've just run out of scratch tokens, you'll have to completely reset two-factor auth (generate a new secret key, so on) to get new scratch tokens.

Limitations

All data pertaining to two factor auth, including the secret key and scratch tokens, is stored in a file called .google_authenticator in a user's home directory. This means that the only security two-factor auth can provide is at attempts to log in to your account by password; once someone is in, they can simply disable the system by deleting the file. Likewise, two factor auth is not intended to be a substitute for strong passwords, but instead a supplement. Keep all passwords secure, and make sure to keep all your SSH keys secure, as they bypass two-factor authentication!

Note that you cannot change the permissions (using chmod, chown, chgrp, or chattr) on the .google_authenticator file, as this will cause the PAM module to refuse to read the file and lock you out of your account!

Likewise, editing the file is extremely inadvisable. The only way to create new emergency scratch tokens is to re-run the setup process from the beginning, as discussed earlier. Manually adding tokens will not work, and editing the file may cause you to lock yourself out of your account! In short, the only safe way to edit your .google_authenticator file is through the setup process!