Libre TOTP
This guide will use github.com as an example; but the same (approximate) procedure works generally with most websites which require a TOTP password.
Libre 2FA login with oathtool
The initial setup is race against the clock. The entire procedure must be completed within a time-frame which ranges from 1-30 seconds, starting from when the "Setup authenticator app" page appears. If you fail, you will need to reload the "Setup authenticator app" page to get a fresh key, and start over. Annoying? You betcha! Don't look at me. I did not invent this dance routine, and I would not impose it on anyone.
First, to save a few precious seconds during the initial setup, and to make the process more secure and easier in the future, we will be creating two text files (the file names and locations can be anything you like):
$ mkdir --mode=700 ~/private $ install -m600 /dev/null ~/private/github-totp $ install -m600 /dev/null ~/private/github-totp-key
Next, open 'github-totp' with your favorite text editor and add these contents:
#!/bin/sh oathtool --totp=SHA1 --digits=6 --time-step-size=30s --base32 @$HOME/private/github-totp-key
Note that the '@' character is important; and be sure to type $HOME or the absolute path to 'github-totp-key'. Tilde expansion '~/' will not work.
Make the 'github-totp' file read-only, executable, and private:
$ chmod 500 ~/private/github-totp
Now, open 'github-totp-key' with your favorite text editor and don your running shoes.
Log into github.com. If you do not see the "Setup authenticator app" page immediately, browse to it like so:
- Click on your profile image (top-right), then click "Settings".
- Click "Password and authentication" under the "Access" section of the left-side nav-bar.
- Click "Enable two-factor authentication" under the "Two-factor authentication" section.
Once the "Setup authenticator app" page appears, the clock is ticking. Ready, Set, Go!
On the "Setup authenticator app" page, click the "setup key" link beneath the qr-code image. Copy the cryptic number/letters shown into the 'github-totp-key' file and save it. The number/letters should have no spaces and no new-line at the end. If you type it by hand, note that there are no zero '0' characters. If you see any, those are the capital letter 'O' characters.
Now, execute the 'github-totp' script.
$ ~/private/github-totp
The command output should be a 6-digit number. Copy that number into the "Verify the code from the app" text-box on the "Setup authenticator app" page.
With any luck, you did all that quickly enough; and yer good to go. Well, almost.
Next you should see bunches of number/letters on a "Save your recovery codes" page. At the very least, you will need to click the "I have saved my recovery codes" button to complete the process. You should probably print those recovery codes now though, or download them and store them securely/privately on another computer, CD/DVD, or USB stick.
The next time you login to github.com, and forever into the future, you will need a TOTP (a 6-digit number) for login. Simply execute the 'github-totp' script again, and use the 6-digit number it generates to log in. Again, you have between 1 and 30 seconds to complete the login. Each time the 'github-totp' script is run, it will produce a different 6-digit number, which expires _sometime_ within the next 30 seconds. Copy that number into the Github login page and press the "Sign-in" button.
I suggest trying that now, in a different web browser, without logging out of your current session, just to make sure it all works. If you logout now and something went wrong, you may have created a major problem, especially if you did not save those recovery codes. Please don't blame me or the oath-toolkit team if things go awry. Direct all complaints toward the website operators who imposed this extra rigamarole upon you.
Lastly, make the 'github-totp-key' file read-only and private:
$ chmod 400 ~/private/github-totp-key
Congratulations. You are safe now. Here are a few more things that you can do for extra peace of mind.
In full disclosure, security fans will indeed tell you that this is insecure; because the auth key is stored on the same machine as your web browser. However, it is no less secure than how people have been logging into websites since the web has existed. Yer a big kid. Decide for yourself.
Optionally, you could keep the 'github-totp' script on a USB stick for a decent level of security, replacing '@$HOME/private/github-totp-key' with the literal key. Let's call that "1.5FA". In the words of Sir Paul, "Close enough for the Skiffle!". The 'github-totp-key' file is not strictly needed. I demonstrated it; because you also may want encrypt that file with GPG for an extra decent level of security. Can never be too safe ya' know.
If you encrypt the 'github-totp-key' file, you will of course, need to decrypt it upon each use in the 'github-totp' script; which will consume a few more precious seconds of the login window. The '@FILE' argument to the `oathtool` command can be replaced with a dash '-' character, which accepts the clear-text key via STDIN.
| This guide is offered under the 'CC0 1.0 Universal' license. No attribution required. |
